docs: 收尾（阶段 8）——部署文档 + 端到端走查 + 文档状态

- docs/delivery/部署文档.md：前置条件 / 环境变量 / 一条命令链 / systemd 与 Nginx 示例 / 首次运行检查 / 运行约束（后端单实例 · 3 天窗口 · 主密钥 · 401 摘除）/ 升级 / 排查 - 从零端到端走查：清库 → db:push → 启动（空转 + QPU 基线）→ 管理面登记 → 引擎立即补一轮（984 条）→ 查看面查询（未折算「—」）→ 补录购买记录 → 金额出现 → 换算参数时间线；无 pageerror - 8 篇设计文档状态 → 已实现（2026-09-15） - README：状态行 / 文档地图（含 delivery）/ 下一步（部署 + 待补验与裁决清单） - AGENTS.md：项目速览更新
2026-09-15 01:10:55 +08:00
parent fca01798e2
commit 0e9db439ba
11 changed files with 179 additions and 23 deletions
@@ -0,0 +1,152 @@
+# 部署文档
+
+> 交付给实例运营方的安装与运行说明——**一条命令链**可跑（见 §3）。前后端**独立部署**：后端单进程常驻；前端为静态产物，由反代托管。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-09-15） |
+| 适用 | new-api-key-usage（针对 NewAPI 的 key 用量统计工具） |
+| 关联 | `README.md`（项目全景与设计依据）· 仓库根 `.env.example`（环境变量样例） |
+| 不含 | 反向代理软件本身的安装（假定服务器已有 Nginx 或等价物） |
+
+---
+
+## 0. 前置条件
+
+| # | 项 | 要求 |
+|---|----|------|
+| 1 | 服务器 | Linux x86_64；可**出网访问 NewAPI 站点**（工具需轮询其接口） |
+| 2 | 运行时 | **Bun ≥ 1.4**（安装：`curl -fsSL https://bun.sh/install \| bash`） |
+| 3 | 数据库 | **PostgreSQL ≥ 14**（可用服务器现有实例；建议新建独立库与独立账号） |
+| 4 | 反向代理 | Nginx 或等价物——**必须能配置 `/api` 反代规则**（前后端连线以同域反代为主，见 README 工程注记） |
+
+## 1. 交付物
+
+- 源码（git 仓库或压缩包），根目录为 Bun workspaces monorepo：
+  - `apps/server` —— 后端（Hono API + 同步引擎同进程）
+  - `apps/web` —— 前端（构建为静态产物 `apps/web/dist`）
+  - `packages/shared` —— 前后端共享的契约类型
+- 无预编译产物要求：后端由 Bun 直接运行 TypeScript；前端产物在部署机执行一次构建即可。
+
+## 2. 环境变量
+
+在仓库根创建 `.env`（**不入库**）：
+
+| 变量 | 必填 | 说明 | 生成 / 填法 |
+|------|------|------|------------|
+| `PORT` | 否 | 后端监听端口（默认 3000） | 如 `3000` |
+| `DATABASE_URL` | **是** | PostgreSQL 连接串 | `postgres://用户:密码@主机:5432/库名` |
+| `MANAGE_TOKEN` | **是** | 管理面口令（`X-Manage-Token`） | `openssl rand -hex 16` |
+| `KEYS_MASTER_KEY` | **是** | 凭证主密钥（**丢失 = 全部 key 需重新登记**） | `openssl rand -base64 32`（32 字节 base64） |
+| `NEWAPI_BASE` | **是** | 上游 NewAPI 站点地址（不带尾斜杠） | 如 `https://your-instance.example.com` |
+
+> `UPSTREAM_SOURCE` / `NEWAPI_FIXTURE_DIR` 仅开发期使用（见实施计划 §6），**生产不要设置**（默认走真实站点）。
+
+## 3. 一条命令链
+
+在仓库根依次执行：
+
+```bash
+bun install                                   # 1) 安装全部依赖（含前端）
+
+bun run db:push                               # 2) 建表（首次；四张表 + 索引）
+                                              #    生产首次也可用 db:generate + db:migrate（迁移文件入库）
+
+bun run --filter '@naku/server' start         # 3) 启动后端（前台；常驻见 §4）
+                                              #    启动即跑一轮同步，随后每 5 分钟一轮
+
+bun run build                                 # 4) 构建前端产物 → apps/web/dist
+```
+
+## 4. 常驻运行（systemd 示例）
+
+`/etc/systemd/system/naku-server.service`：
+
+```ini
+[Unit]
+Description=new-api-key-usage server
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/opt/new-api-key-usage/apps/server
+# .env 由应用从仓库根读取（apps/server 的上两级）
+ExecStart=/root/.bun/bin/bun run /opt/new-api-key-usage/apps/server/src/index.ts
+Restart=always
+RestartSec=5
+# 可选：环境变量也可直接注入（优先级高于 .env）
+# Environment=PORT=3000
+# Environment=DATABASE_URL=postgres://...
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+systemctl daemon-reload && systemctl enable --now naku-server
+journalctl -u naku-server -f          # 观察 [sync] 日志
+```
+
+## 5. 反向代理（Nginx 示例）
+
+```nginx
+server {
+    listen 80;
+    server_name usage.example.com;
+
+    # 前端静态产物（同源，前端用相对路径 /api）
+    root /opt/new-api-key-usage/apps/web/dist;
+    index index.html;
+    location / {
+        try_files $uri $uri/ /index.html;   # SPA 路由回退
+    }
+
+    # 后端 API（前后端连线：同域反代）
+    location /api/ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+> 跨源直连（前端与后端不同域）亦可，但需后端 CORS 白名单与前端运行时 API base（契约 约定 24）；同域反代是默认形态、无 CORS 问题。
+
+## 6. 首次运行检查
+
+1. 后端日志出现两行：`[sync] 引擎启动：立即跑一轮，随后每 5 分钟一次` 与 `[sync] 轮次完成：0 key，成功 0，失败 0，新增日志 0 条…`（无 key 时正常空转）
+2. 打开站点 → 管理面 `/manage/api-keys`（界面上不暴露入口，直接输入 URL）→ 输入 `MANAGE_TOKEN` 进入
+3. 点「+ 登记 key」粘贴一个 sk-key → 登记成功后该 key 出现在清单（「数据截止」先显示「同步中」，一轮后变为时间）
+4. 回到查看面 `/usage-log`，粘贴刚登记的 key → 查询 → 卡片与明细出现数据
+
+## 7. 必须知道的运行约束
+
+| # | 约束 | 说明 |
+|---|------|------|
+| 1 | **后端必须单实例** | 同步引擎随进程启动（5 分钟一轮）。多实例会重复轮询、互相覆盖 `log_synced_at`，并可能触发上游限流。systemd 单实例 + 不做水平扩展即可 |
+| 2 | **3 天窗口** | 上游 `/api/log/token` 固定只返回最近 1000 条（当前速率下 ≈ 3 天）。同步停摆超过约 3 天，旧日志**永久丢失**（上游不提供回填接口）。日志落后 > 24h 时每轮打印 warning |
+| 3 | **`KEYS_MASTER_KEY` 不可丢** | 该密钥加密存储全部 sk-key。丢失后无法解密 → 需在管理面重新登记全部 key（历史日志数据仍在） |
+| 4 | **401 自动摘除** | 连续 3 轮返回 401 的 key 会被自动停用（`disabled_source = auto_401`）；在管理面「启用」即可恢复（启用时会向上游验证） |
+| 5 | **上游同站点共享** | 工具对上游的请求是只读查询（每 key 每 5 分钟 2 个请求），量级极小；若上游有更严格的限流策略，可调低 key 数量或延长周期（`apps/server/src/sync/policy.ts` 的 `TICK_MS`） |
+| 6 | 真实 key 联调 | **待作者补验**：本地开发以实测响应快照验证（实施计划 §6），首次对真实站点登记时请在管理面确认「上游验证通过 + 首轮同步完成」 |
+
+## 8. 升级流程
+
+```bash
+git pull                                       # 或替换源码目录
+bun install                                    # 依赖有变化时
+bun run db:push                                # schema 有变化时（会提示确认）
+bun run build                                  # 重建前端产物
+systemctl restart naku-server                  # 重启后端（引擎随启动立即补一轮）
+```
+
+## 9. 故障排查
+
+| 现象 | 排查方向 |
+|------|---------|
+| 查看面「数据截止」显示「数据同步中…」 | 后端日志 `[sync]` 是否有该 key 的失败行；新登记 key 等一轮即可 |
+| 查看面长时间数据不更新 | 是否「已失效（auto_401）」——管理面看状态徽章；或后端是否在运行 |
+| 登记返回「上游暂不可用」 | 服务器到 `NEWAPI_BASE` 的网络连通性（`curl -sS $NEWAPI_BASE/api/status`） |
+| 页面加载但查询 502 | 反代 `/api` 规则与后端端口是否一致 |
+| 金额列显示「—」 | 该日志所属订阅尚未登记购买记录 → 管理面「购买记录」按观测提示补录 |
+| 管理面全部 401 | `MANAGE_TOKEN` 与请求头是否一致（口令存 sessionStorage，关标签后需重新输入） |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-13：约定层 23 条 + 逐页端点——四页推完、`/dashboard` 二期占位） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/design/交互设计.md`（页面清单与职责）· 四张表字段设计（数据形状）· `docs/design/交互设计.md` §0（管理面边界与口令门帘） |
 | 范围 | 路径、鉴权形态、时间 / 数字形态、分页、错误与响应形状、逐页端点；校验细节、存储、调度归技术稿 |
 | 不含 | 上游 NewAPI 的调用方式（同步引擎设计）· 展示文案与交互细节（交互设计细节层） |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-11，逐字段讨论收敛；2026-09-13 修订：key 登记改由管理通道执行、表名更改为 `api_keys`、新增 `disabled_source` 列） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/upstream/NewAPI-sk-key接口文档.md`（接口①字段依据）· `docs/upstream/NewAPI-接口范围.md` · `docs/design/API契约.md` §2.2（登记 / 启停端点） |
 | 定稿范围 | 列结构 + 语义 + 写入时机；同步引擎细节（401 阈值等）不在此文 |
 | 字段数 | 17 = 9 本系统管理字段 + 8 上游接口字段 |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-13，多轮讨论收敛；同日修订：查看面金额口径改「折算实付人民币」，§6 边界相应放开） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/design/qpu_history表字段设计.md`（折算链第一条：quota → 额度美元）· `docs/design/API契约.md` §2.3（登记 / 编辑端点）· `docs/upstream/NewAPI-sk-key接口文档.md`（`other.subscription_*` 字段依据） |
 | 范围 | 列结构 + 语义 + 写入时机；登记入口见 API 契约 §2.3 |
 | 字段数 | 9 = 1 主键 + 8 人工录入（登记 4 · 期间 2 · 订阅 2） |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-13，多轮讨论收敛：只读化、按购买时刻取尺） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/design/purchases表字段设计.md`（折算链第二条：额度美元 → 实付人民币）· `docs/design/API契约.md` §2.4（只读查看端点）· `docs/upstream/NewAPI-接口范围.md`（采集来源 `/api/status`） |
 | 范围 | 列结构 + 语义 + 写入规则；采样调度（同步引擎）不在此文 |
 | 字段数 | 3 = 1 主键 + 2 业务字段 |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-11，逐字段讨论收敛） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/upstream/NewAPI-sk-key接口文档.md`（接口②字段依据）· `docs/design/api_keys表字段设计.md`（`key_id` 外键指向） |
 | 定稿范围 | 列结构 + 去重与写入策略；同步引擎细节（调度、401 处理）不在此文 |
 | 字段数 | 23 = 20 上游字段 + 3 系统字段（上游响应共 21 个字段，其中展示序号 `id` 不落表，见 3.2） |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-13：方向层 + 跨页共性 10 条 + 逐页细节五节全部落定） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `README.md`（决策与事实）· `docs/design/API契约.md`（数据形状依据） |
 | 范围 | 方向层（页面集合 + 职责）+ 细节层（跨页共性 + 逐页细节） |

@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-13：17 条议题全部落定——见 §2 结论索引与 §3 决策记录） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/upstream/NewAPI-接口范围.md`（上游调用与失败语义）· 四张表字段设计（写入时机）· `docs/design/API契约.md`（查看面消费的数据形状）· `README.md`（既定决策与关键事实） |
 | 范围 | 调度与执行、失败处理、可观测、部署初始化 |
 | 不含 | 前端交互（交互设计）· HTTP 契约（API 契约，已定稿）· 多实例协调 / 历史回填 / 告警渠道（见 §4） |
@@ -4,7 +4,7 @@

 | 项目 | 内容 |
 |------|------|
-| 状态 | 定稿（2026-09-14；**进度表随 loop 持续更新**） |
+| 状态 | 已实现（2026-09-15） |
 | 关联 | `docs/design/API契约.md` · `docs/design/同步引擎设计.md` · `docs/design/交互设计.md` · 四张表字段设计 · `AGENTS.md`（命令） |
 | 范围 | 阶段划分、每批验收标准、loop 机制与推进规则；技术细节一律以设计文档为准 |
 | 当前进度 | 阶段 0–7 已完成；下一批：**阶段 8**（收尾：部署文档 + 端到端走查 + 文档状态更新） |
@@ -65,7 +65,7 @@
 | 5 | **查看面数据面**：`logs/query` + `summary` + 折算链（按购买期间分段取尺） | curl 实测：字段齐全、`meta.data_until` 取最慢、金额按购买分段累加；**无归属购买的行 `amount_rmb = null` 且计入 `unpriced_count`**（2026-09-14 定） | ✅ 2026-09-15（56 项单测绿；curl 17 步——明细字段齐全 / 分页 / type 过滤 / 参数校验 6 类 400 / 未收录 200 空结果 / `data_until` 取最慢 / 金额按归属购买折算、未折算行 `null` + `unpriced_count` 计数正确） |
 | 6 | **前端 `/usage-log`**：筛选区（key 标签 + datetimerange + 快捷项）· 卡片 · 表格 + 展开行 · 分页器 · 六种状态模式 | 浏览器实测：seed 数据走一遍；六态逐一可见（加载 / 初始 / 未收录 / 无记录 / 同步中 / 失败）；金额为 `null` 显示「—」 | ✅ 2026-09-15（Playwright + 系统 Chrome 逐态断言：初始 / 加载 / 查询（卡片 984 · 298,041,838 · 4.90）/ 展开行 / 翻页 / 未收录 / 无记录 / 同步中 / 失败，无 console 错误；金额 `null` 显示「—」并伴未折算提示条） |
 | 7 | **前端管理面**：口令门帘 + 侧边栏 + 三页（key 管理 / 购买记录含核对提示与补录 / 换算参数） | 浏览器实测：登记、启停、CRUD、补录、时间线全操作 | ✅ 2026-09-15（Playwright 走查 15 步：错口令 → 门帘提示 / 正确口令进入 / 展开行 / 登记三类结果（拒绝 · 成功 · 已登记）/ 停用（确认弹窗）与启用 / 核对提示 / 补录（预填订阅 ID 与观测额度）/ 编辑 / 删除（确认弹窗）/ 换算参数「当前生效」/ 返回查看面；顺带补 naive-ui 中文 locale 与表格横向滚动） |
-| 8 | **收尾**：部署文档（`docs/delivery/`）· 端到端走查 · 文档状态更新（设计文档 → 已实现） | 一条命令链可部署（前后端独立 + 后端单实例注记）；走查无阻 | ☐ |
+| 8 | **收尾**：部署文档（`docs/delivery/`）· 端到端走查 · 文档状态更新（设计文档 → 已实现） | 一条命令链可部署（前后端独立 + 后端单实例注记）；走查无阻 | ✅ 2026-09-15（`docs/delivery/部署文档.md` 交付；**从零端到端走查**：`db:push` 建表 → 启动（空转 + QPU 基线）→ 管理面登记 → 引擎立即补一轮（984 条）→ 查看面查询（未折算「—」）→ 补录购买记录 → 金额出现 → 换算参数时间线；8 篇设计文档状态改「已实现」） |

 ## 4. 待定问题