new-api-key-usage/docs/delivery/部署文档.md

部署文档

交付给实例运营方的安装与运行说明——一条命令链可跑（见 §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. 一条命令链

在仓库根依次执行：

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：

[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

systemctl daemon-reload && systemctl enable --now naku-server
journalctl -u naku-server -f          # 观察 [sync] 日志

5. 反向代理（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. 升级流程

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，关标签后需重新输入）