ai-kefu-admin/docs/superpowers/plans/2026-10-14-phase4-deploy-migration.md

# Phase 4：部署与迁移实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 交付上线全部工件：Docker 两阶段构建与生产 compose、admin dist 的 FastAPI 服务、存量数据导入脚本、数据归档脚本、部署手册（继承 jc 血泪）、切换 runbook；顺手清 Phase 4 清理单中部署相关项。

**Architecture:** 单容器（python:3.13-slim + admin dist 拷入）；FastAPI 在 `/admin/` 前缀服务 SPA（history fallback 限定该前缀）——反代层可走"独立管理域名指到同容器"或"路径分流"两形态（spec §7.1 同源零 CORS）；存量导入用 scripts/import_legacy.py（保 conversation_id/session/page_token/status，幂等，对账报告）。

**Tech Stack:** Docker multi-stage（node:20-alpine 构建 admin → python:3.13-slim）；其余同现状。

**参照 spec:** §8（数据迁移）、§9（部署全部条目——逐项对照落实）；CLAUDE.md「Phase 4 部署记档」与「Phase 4 清理单」9 项。

**重要边界：本阶段交付部署工件（代码/脚本/文档/配置模板），不执行实际部署。** 实际部署到阿里云时按用户全局 SOP 另行确认流程（全局 CLAUDE.md 规程）。

---

### Task 1: admin 生产服务与 Docker 两阶段构建

**Files:**
- Modify: `app/main.py`（挂 /admin/ 静态 + SPA fallback）、`Dockerfile`（新建两阶段）、`docker-compose.yml`（新建）、`.dockerignore`（新建）
- Test: `tests/test_admin_serving.py`

- [ ] 失败测试：
  - `GET /admin/` 返回 index.html（dist 存在时）；`GET /admin/assets/xxx` 静态可达；未知路径 `/admin/xxx` fallback 返回 index.html（**加固项**：admin 实为 hash 路由非必需，但深链/刷新兜底；**fallback handler 必须只对 /admin 前缀生效，非 /admin 的 404 保持默认 JSON**——防 API 404 被 SPA 吞）；`/admin` 前缀**不经过租户中间件解析**（豁免规则扩 `/admin`——精确 `== "/admin" or startswith("/admin/")`，防 `/admin-evil`）；dist 不存在时（本地测试环境）`/admin/` 返回 503/404 带说明（开发用 pnpm dev，不炸整个应用）
  - **/health 分级（spec §9 明文）**：进程状态 + 各租户 engine 状态 + 域名表版本；单租户库损坏 → 200 带 per-tenant degraded（不整体 500）；registry.runtimes() 逐租户探库（轻查询，如 `SELECT 1`）
- [ ] 实现：
  - main.py：`ADMIN_DIST = BASE_DIR / "admin" / "dist"`；存在则挂 StaticFiles(directory=dist, html=True) 到 `/admin`——SPA fallback：自定义 404 handler 限定 `/admin/*` 回 index.html（读 dist 结构确认 assets 子目录）
  - host_middleware 豁免扩 `/admin`；`/health` 升级为分级响应（上述测试钉死）
  - Dockerfile：阶段一 node:20-alpine（WORKDIR /build、拷 admin/、corepack enable + **package.json 的 packageManager 字段钉 pnpm 版本**、pnpm install --frozen-lockfile、`VITE_BASE_URL=/admin/ pnpm build`——**资源前缀必须 /admin/ 否则挂前缀后白屏**）；阶段二 python:3.13-slim（拷 app/ static/ seed_profiles/ scripts/ requirements、pip install、COPY --from=build /build/admin/dist admin/dist）；CMD uvicorn --workers 1
  - docker-compose.yml：`name: all-kefu`（互删教训）；单 app 服务；端口 8018:8018；env_file .env；volume `./data:/app/data` + `./tenants:/app/tenants`；TZ=Asia/Shanghai；mem_limit 768m；logging json-file max-size 10m max-file 3；healthcheck **CMD-SHELL 用 python urllib（slim 无 curl）**打 /health
  - .dockerignore：.venv、**`**/node_modules`、`admin/dist`**（裸 node_modules/dist 只匹配根）、.worktrees、tests、docs、data、tenants、platform.db*、.git
- [ ] 验收：后端全量（595+新增）+ admin `VITE_BASE_URL=/admin/` 构建后本地起 FastAPI 验证 /admin/ 服务与资源路径（冒烟）+ `docker compose build` 成功（本机 Docker 可用则构建验证，不可用则文档注明服务器构建）
- [ ] 提交 `feat: admin 生产服务(/admin SPA fallback) + Docker两阶段构建 + 生产compose`

### Task 2: 存量导入脚本 import_legacy.py

**Files:**
- Create: `scripts/import_legacy.py`、`tests/test_import_legacy.py`

- [ ] 失败测试（老库路径经 env 指路（如 ALL_KEFU_TEST_LEGACY_JC/AUTO），**缺失则 skipif**——机器相关且含真实数据；测试只拷结构+少量行到 tmp 或造脱敏小库）：
  - 导入 jc 库 → 租户库（bootstrap 后的 jiancai）行数一致（五表对账 + **最近 10 条会话抽查**【spec §8 原文】）；**conversation_id 原样**（external_key 连续性）；session_id/page_token/status 原样；pending 推送日志 → failed 加注；**幂等**（跑两遍第二遍零变化）
  - auto 库同理
- [ ] 实现：读老库（aiosqlite 只读）逐表 SELECT → 按目标租户库 INSERT OR IGNORE（幂等键：conversation_id/表主键）；对账报告（每表 行数源/目标/跳过 + 抽查 10 条摘要）；`--source <db路径> --tenant <slug>` CLI；README 用法段
- [ ] 提交 `feat: 存量导入脚本（保ID/session状态、pending→failed、幂等、对账）`

### Task 3: 数据归档脚本 archive.py

**Files:**
- Create: `scripts/archive.py`、`tests/test_archive.py`

- [ ] 失败测试：造 >N 天会话 → 归档（导出 JSON 到 data/archives/）→ 清库 → VACUUM → 库文件变小；<N 天不动；--dry-run 只列不动
- [ ] 实现：`--tenant slug --days N（默认 365） --dry-run`；删除序（lead_push_logs→evaluations→profiles→messages→conversations，倒 FK 序）；导出含完整行；VACUUM；报告
- [ ] 提交 `feat: 数据归档脚本（导出/清理/VACUUM/dry-run）`

### Task 4: 部署手册与 openresty 模板

**Files:**
- Create: `docs/deploy-production.md`、`deploy/openresty-all-kefu.conf.template`

- [ ] deploy-production.md 章节（**继承 jc 血泪手册全部条目** + CLAUDE.md Phase 4 记档落位）：
  1. 环境与前置（服务器、Python/Docker、**pip install -r requirements.txt 含 python-multipart**、**ADMIN_PASSWORD 必设**（默认值启动警告）、TENANT_SOURCE=db）
  2. 首次部署流程：clone → .env（逐项说明）→ bootstrap_platform.py（超管引导+两租户导入）→ docker compose up → 健康检查
  3. 反代配置（1Panel）：租户域名→127.0.0.1:8018；**admin 两形态**（独立域名 或 路径分流到 /admin）；WS 单套升级头；/static/widget.js no-cache；**/api/public 放行**（头像）；主 conf include 行检查；nginx -t 后 reload
  4. 存量迁移：老项目 db 拷贝纪律（**停老容器或 SQLite backup API/VACUUM INTO 导出，禁运行时裸 cp**）→ scp 到新机 → import_legacy.py → 对账核对
  5. 切换 runbook（独立节）：验证清单（不切域名全功能验证）→ 切反代 → 观察一周（breach_rate、推送成功率、磁盘）→ 老项目停用归档
  6. 日常运维：备份（platform.db + tenants/ 用 SQLite backup API，**禁运行时直拷**；季度恢复演练）、日志（封顶已配；**PII 对齐**：引擎日志现存会话内容摘录，与 spec §9"不打聊天内容"冲突——手册如实记当前状态并在观察期收口）、归档（archive.py 用法）、升级发版（build 后打版本 tag、compose image: 引用 tag，回滚=改 tag up 30 秒）、**加租户=反代加一条不起容器**、bootstrap 执行位置（`docker compose run --rm app python scripts/bootstrap_platform.py`）
  7. 踩坑实录（继承 jc：compose 撞名互删、WS 426、widget 缓存、1Panel include、bottom-left 溢出 + 本项目新增：mem_limit、TZ、/api/public 404）
- [ ] openresty 模板：完整可抄配置（upstream + 租户 server 块 + admin server 块两形态注释 + WS + 缓存策略）
- [ ] 提交 `docs: 部署手册（继承jc血泪+切换runbook+备份演练）+ openresty模板`

### Task 5: 清理单部署相关批次

**Files:**（按清理单逐项）
- resolver 回退链接入 platform_settings——**架构方向（同步 resolver 无法读异步 DB）**：lifespan 启动把 platform_settings 快照进内存 dict + PUT /settings 提交后刷新快照（workers=1 下与内存 token 表同模式）；回退链 = 租户槽位 → 快照 → env；测试覆盖：设置 ai.api_key 后租户空槽取它、PUT 后即时生效、快照缺失回退 env
- email/test 与 push/test 限流（复用 LoginLimiter 模式，5 次/15 分钟每租户）
- ECharts 收窄（plugins/echarts.ts 只注册 Bar/Line/Pie + 现用组件）+ 租户切换器 useTenantOptions composable 收拢三页（conversations/config/stats）
- 锁屏/通知组件代码删除（enabled:false 已不可达——删组件文件与配置项，grep 确认零引用）
- [ ] 每项独立提交；全量回归（后端+vitest+build）
- [ ] 提交（多项分别提交）

### Task 6: Phase 4 收尾

- [ ] 全量回归（根+tests/ 双跑；vitest；build；docker compose build 复验）
- [ ] CLAUDE.md/README 终态更新（项目完成状态、清理单结项核对、上线前检查清单浓缩版）
- [ ] 提交 `chore: Phase 4 收尾——部署工件齐备`

---

## 显式不做（Phase 4 范围外）

实际部署执行（按全局 SOP 另行确认）；真实域名 DNS 变更；UniService 侧配置；CI/CD 流水线；监控告警系统（推送失败告警二期）。

## 执行注意

部署工件全部本地可验证（构建/测试/文档）；涉及真实服务器的步骤只写进 runbook 不执行。清理单 Task 5 允许按耗时裁剪（resolver 接线若超半日可单独挂回清单——但它是平台设置页的功能闭环，优先保）。