From c6d323081ce3a1d38cdf88de047574ac132f68d3 Mon Sep 17 00:00:00 2001 From: flym Date: Fri, 11 Sep 2026 22:06:39 +0800 Subject: [PATCH] docs: record 2026-09-11 production deployment (ad87a71) --- docs/production-deployment-2026-09-11.md | 36 ++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/production-deployment-2026-09-11.md diff --git a/docs/production-deployment-2026-09-11.md b/docs/production-deployment-2026-09-11.md new file mode 100644 index 0000000..56552e1 --- /dev/null +++ b/docs/production-deployment-2026-09-11.md @@ -0,0 +1,36 @@ +# 生产部署记录（2026-09-11） + +## 发布 + +- 发布提交：`ad87a71`（含 `de6fdb0` 邮箱/短信注册验证、`c439ccb` 图形验证码+唯一用户名、`5b9d74a` 用户资料管理与管理员删除用户、`57c854a`/`080af11`/`70f64b6`/`be7e1f4` CMS 入口修复、`ad87a71` 品牌 favicon 等）。 +- 发布目录：`/home/flym/releases/ad87a71`（www + API）、`/home/flym/releases/cms-ad87a71`（CMS）。 +- 软链：`kaotings-www`→`releases/ad87a71`、`kaotings-cms`→`releases/cms-ad87a71`、`kaotings-api`→`releases/ad87a71/services/api`。 +- 数据库迁移：`005_sms_provider.sql`、`006_usernames.sql` 已应用（`schema_migrations` 001–006 齐全，`users.username` 列存在）。 + +## 本次发现并修复的问题（重要） + +1. **Turbopack 外部模块缺失导致 CMS 500**：Next 16（Turbopack）生产构建会把外部依赖（pino/pg/drizzle-kit/pino-pretty，带内容 hash 后缀）拷贝到 `.next/node_modules/-/`，运行时按该名字 require。 + - 本地 Windows 构建产物中 `.next/node_modules/` 只有空目录（文件未写入），导致此前发布（含 09-11 上午 `cms-57c854a` 包）的 CMS 管理端/API 一直 500（`Cannot find module 'pino-'`），www 首页因调用 CMS API 连带 500。 + - 修复：以 `releases/df6a0e4/apps/cms/.next/node_modules`（同版本依赖、hash 一致）覆盖 `cms-ad87a71/.next/node_modules` 后 CMS 恢复正常。 + - 教训：**本地（Windows）构建的 CMS `.next` 不可直接用于生产**；后续 CMS 应在服务器上构建，或发布前校验 `.next/node_modules` 文件完整性（pino 包应 ≥200 文件）。 +2. **服务器资源**：内存 1.9G 无 swap，服务器上跑 CMS 构建会 OOM（本次已加 4G `/swapfile`）。 +3. **sudo 构建残留 root 属主文件**：曾以 sudo 在发布目录内跑 `npm run build`，产生 root 属主的 `.next` 文件，导致后续以 flym 提取覆盖失败；已清理。发布目录内构建/清理应统一属主。 +4. **SSH 未认证连接限流**：该服务器 sshd 未认证并发限制很严（疑似外部扫描占用 MaxStartups），部署期间需控制连接频率、合并操作。 + +## 回滚 + +- 上一可用发布保留：`releases/080af11`（www）、`releases/cms-57c854a`（CMS，已修复 `.next/node_modules` 与 `node_modules`，可独立运行）。 +- 回滚：软链指回上述目录 + `systemctl restart` 对应服务。API 回滚需同时评估 `005/006` 迁移（均为新增列/表，旧代码兼容，可保留迁移）。 + +## 验收 + +- `systemctl is-active kaotings-api kaotings-cms kaotings-web`：active ×3。 +- `GET /healthz`（127.0.0.1:8000 与 https://www.kaotings.com）：ok / 200。 +- www：`/`、`/register`、`/login`、`/icon.png` 均 200（新代码标记 favicon 生效）。 +- CMS：`/cms/admin` 200；`/cms/api/products?where[status][equals]=published` 200。 +- API 门禁：`/api/v1/auth/me` 未登录 401。 + +## 备注 + +- 生产 `api.env` 尚未注入 SMTP/阿里云短信凭据（新配置项默认空值=功能关闭），注册验证能力待凭据注入后启用，属待办而非本次部署内容。 +- Caddy 未改动（CMS 根路径跳转由 CMS 自身 `/cms → /cms/admin` 处理）。