襷の系譜 GitHub 部署与数据同步方案

日期：2026-06-28

关联文档：

1. 背景

tasuki-keifu 已经在 Ubuntu-3 上完成初始部署：

域名：https://tasuki-keifu.gelatoni.uk
应用目录：/opt/apps/tasuki-keifu
应用端口：127.0.0.1:3020
反向代理：Nginx
运行方式：Docker Compose
数据库：项目独立 PostgreSQL 容器

当前部署是从本地同步代码到服务器，再在服务器上构建镜像、执行迁移、重启容器。

这个方式适合初始验证，但不适合作为长期发布流程。下一步应改为与 personal-site 一致的 GitHub Actions 部署模式。

2. 参考 personal-site 的部署模式

personal-site 当前模式：

GitHub 私有仓库作为代码源。
push 到 main 后触发 GitHub Actions。
Actions 执行依赖安装、类型检查、应用构建。
Actions 构建 Docker 镜像。
将镜像保存为 tar.gz artifact。
通过 SSH/SCP 上传镜像包和 compose 文件到 Ubuntu-3。
服务器执行 docker load。
服务器用 Docker Compose 重启服务。

这个模式的优点：

服务器不需要保留 GitHub token。
服务器不需要作为 git checkout 工作区。
CI 构建环境更干净，失败更容易定位。
部署入口统一为 git push main。
与现有个人站点运维方式一致。

tasuki-keifu 可以复用这个模式，但需要额外处理数据库迁移。业务数据补全先不纳入部署流程。

3. 推荐部署目标

3.1 仓库

建议创建 GitHub 私有仓库：

gelatoni-xh/tasuki-keifu

短期先私有。等数据来源、版权边界、页面质量和运维方式更稳定后，再考虑公开。

3.2 分支

短期只需要：

main

发布规则：

push 到 main 自动部署生产。
workflow_dispatch 支持手动部署。

等后续有较多真实数据录入、后台管理、导入脚本之后，再增加：

develop
preview 环境
release tag

V0.1 不需要过早复杂化。

3.3 GitHub Secrets

复用 personal-site 的服务器连接方式：

UBUNTU3_HOST
UBUNTU3_USER
UBUNTU3_SSH_KEY

tasuki-keifu 不应把生产数据库密码、DATABASE_URL 或 .env.production 写入 GitHub Actions。

生产环境变量只保留在服务器：

/opt/apps/tasuki-keifu/.env.production

GitHub Actions 只负责传输镜像和部署文件，不负责导入、同步或修正业务数据。

4. 部署产物

建议仓库内保留：

Dockerfile
docker-compose.prod.yml
deploy/
  ├─ README.md
  └─ nginx-tasuki-keifu.conf
.github/
  └─ workflows/
      └─ deploy.yml

其中：

Dockerfile 用于构建 Next.js + Prisma 应用镜像。
docker-compose.prod.yml 描述 app 和 PostgreSQL；生产部署优先使用 Actions 上传的镜像，本地应急时仍可 build。
.env.production 不进入仓库。
Nginx 配置文档化，但不必每次部署覆盖。

5. GitHub Actions 流程

推荐流程：

push main
  └─ build
      ├─ checkout
      ├─ setup pnpm / Node.js
      ├─ pnpm install --frozen-lockfile
      ├─ pnpm prisma:generate
      ├─ pnpm lint
      ├─ pnpm build
      ├─ docker build -t tasuki-keifu-app:latest .
      └─ docker save tasuki-keifu-app:latest | gzip

  └─ deploy
      ├─ upload image archive and compose file
      ├─ docker load
      ├─ docker compose run --rm app pnpm prisma migrate deploy
      ├─ docker compose up -d app
      ├─ docker image prune -f
      └─ health check

注意：

部署流程必须执行 prisma migrate deploy。
部署流程不执行 pnpm db:seed。
seed 只用于本地开发或明确的初始化动作。
生产数据一旦进入数据库，seed 就不能成为常规部署步骤。
业务数据导入、数据同步和数据修正不属于部署流程。

6. 生产数据库策略

生产数据库是 tasuki-keifu 的事实源。

当前：

PostgreSQL container
  database: tasuki_keifu
  user: tasuki_keifu_user
  volume: tasuki-keifu_tasuki-keifu-postgres-data

生产数据库原则：

migration 可以自动执行。
seed 不自动执行。
数据导入脚本不在部署流程中执行。
重要导入前先备份。
数据回滚优先依赖备份恢复，而不是反向 migration。

7. 数据补全与同步策略

数据补全和部署流程先解耦。部署只处理代码和 schema，业务数据由独立的数据补全工作流处理。

7.1 短期：线上数据库作为写入目标

适用阶段：

V0.1 到 V0.2
数据量很小
主要维护者只有站主本人
真实数据录入还在探索模型

目标：

线下 BFS 探索得到的数据可以进入线上数据库。
部署流程不覆盖业务数据。
数据补全和应用发布互不阻塞。

推荐做法：

线下会话负责探索、整理、判断来源可信度。
写入前手动或脚本触发线上备份。
通过受控脚本、后台或明确 SQL 写入线上数据库。
写入动作记录来源和审计信息。
部署只执行 prisma migrate deploy，不执行 seed，不执行导入脚本。

短期允许：

线下会话直连线上数据库补数据。
从线上导出备份到本地，用于页面调试和模型校验。
本地做模型调整后，通过 migration 部署到线上。

短期不建议：

本地数据库直接覆盖线上数据库。
线上部署自动执行 seed。
把数据库 dump 放进 Git 仓库。
在 Actions 里保存生产数据库 dump。
把 BFS 抓取、清洗和导入塞进 GitHub Actions 部署流程。

7.2 封板节点

当某一批数据确认到一定程度，可以做一次“封板”：

线上数据库手动备份。
记录当前数据范围、来源范围和已知缺口。
必要时将备份恢复到本地，作为阶段性开发基准。
后续继续以线上数据库为准推进增量。

封板不是发布动作，也不是代码 tag 的强绑定。它只是数据工作流里的阶段性快照。

7.3 中期：生产为主，本地只做开发

当真实数据明显增加后，应切换为：

生产数据库 = 事实源
本地数据库 = 开发副本

此时规则：

线上数据只通过后台、导入脚本或受控 SQL 修改。
本地只拉取线上脱敏或完整备份用于开发。
本地修改数据不直接同步回线上。
数据修正应以可审计的后台操作、导入脚本或 migration 完成。

中期需要补充：

管理后台
数据导入任务
审计日志
导入前备份
导入结果报告

7.4 长期：数据导入与数据仓库分离

长期可以演进为：

公开页面 / 管理后台
  └─ PostgreSQL 主业务库

导入脚本 / 抓取任务
  └─ staging tables
      └─ 人工确认
          └─ 业务表

分析 / 关系图 / 统计
  └─ warehouse or materialized views

长期重点：

原始来源数据保留。
清洗后数据入业务表。
关系图和统计可以读物化视图或分析库。
生产业务库仍是公开页面的可信数据源。

V0.1 不做这一层，只保留演进方向。

8. 备份策略

当前已经有：

/opt/apps/tasuki-keifu/backup-db.sh
/opt/apps/tasuki-keifu/backups
/etc/cron.d/tasuki-keifu-backup

短期策略：

每日一次 pg_dump。
重要数据录入前手动备份。
重要 migration 前手动备份。
本地开发需要真实数据时，从备份恢复到本地。

后续增强：

备份保留策略明确化，例如保留 14 天。
自动上传到对象存储。
定期做 restore 演练。
备份文件加密。

9. 回滚策略

应用回滚：

保留最近一次镜像 tar 或镜像 tag。
如果新版本页面异常，重新 docker load 旧镜像并 docker compose up -d app。

数据库回滚：

Prisma migration 不做自动反向回滚。
schema 变更前先备份。
如需回滚数据，使用备份 restore。

因此，危险 migration 上线前必须：

本地验证 migration。
生产备份。
执行 migration。
检查核心页面。

10. 与当前手动部署的关系

当前手动部署可以保留为应急路径：

本地代码 -> 同步到服务器 -> docker compose build -> migrate deploy -> compose up

但一旦 GitHub Actions 跑通，常规发布应切换为：

git push main -> GitHub Actions -> Ubuntu-3

手动部署只用于：

GitHub Actions 故障
服务器排障
极早期快速验证

11. 待办

P0：

创建 gelatoni-xh/tasuki-keifu 私有仓库。
初始化本地 git 仓库并推送 main。
新增 .github/workflows/deploy.yml。
调整 docker-compose.prod.yml 支持镜像部署，而不是只依赖服务器 build。
确认 GitHub Secrets 可复用 personal-site 的 Ubuntu-3 配置。
跑通一次 GitHub Actions 部署。

P1：

增加生产部署后的 health check。
增加本地从线上备份恢复的操作文档。
增加手动生产备份命令。
明确 seed 只用于本地开发。

P2：

增加 staging import 设计。
增加导入报告。
增加对象存储备份。
增加恢复演练记录。

2026-06-28-襷の系譜-GitHub部署与数据同步方案