# 生产部署记录（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/<name>-<hash>/`，运行时按该名字 require。
   - 本地 Windows 构建产物中 `.next/node_modules/` 只有空目录（文件未写入），导致此前发布（含 09-11 上午 `cms-57c854a` 包）的 CMS 管理端/API 一直 500（`Cannot find module 'pino-<hash>'`），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` 处理）。