Skip to content

launch-checklist.md

Latest commit

 

History

History
114 lines (85 loc) · 4.94 KB

launch-checklist.md

File metadata and controls

114 lines (85 loc) · 4.94 KB
Raw

上线检查清单

本清单用于每次较大改动后的上线前后核对。项目包含真实校友数据，任何构建、部署和数据库操作都先以“可回滚、可验证、不泄露”为原则。

1. 本地开发完成前

  • 确认当前分支正确，git status --short 中没有意外文件。
  • 不提交 .env、数据库、上传文件、备份包、日志、AGENTS.md、.agents/、.claude/。
  • 如改动较大，先在原终端用 Ctrl+C 停止本项目开发服务，再清理 .next 并重新启动；不要批量结束系统中的所有 Node 进程。
npm run dev
  • 本地开发服务统一使用 http://localhost:3000，避免 3001/3002 等端口残留造成静态资源错配。
  • 移动端优先检查首页、登录/注册、个人中心、校友地图、故事投稿、修正申请、后台主要表单。

2. 本地验证

npx tsc --noEmit
npm run lint
npm run audit:prod

如本地服务已在 3000 端口运行：

SMOKE_BASE_URL=http://localhost:3000 npm run smoke

配置了管理员测试账号时，补充：

SMOKE_BASE_URL=http://localhost:3000 \
SMOKE_USERNAME="<管理员用户名>" \
SMOKE_PASSWORD="<管理员密码>" \
npm run smoke

涉及账号、认证、活动报名或小程序 API 时，必须在隔离数据库执行 acceptance-plan.md 的自动化闭环。

3. 数据安全

  • 本地 prisma/dev.db 可能是真实数据，测试脚本不要打印完整姓名、邮箱、手机号、token 或密码哈希。
  • 触碰 schema、数据清洗、导入、批量更新前先备份数据库。
  • 生产发布前备份 /var/www/alumni-site/data/prod.db 和 /var/www/alumni-site/uploads。
  • 真实 staging 已通过 npm run check:staging:external，且没有使用 localhost、示例发件地址或复用 OAuth 凭据。
  • npm run test:staging:https 已验证 DNS、证书、健康检查和安全响应头。
  • npm run test:staging:email 已发送并在收件箱实际收到验收邮件。
  • public/uploads/ 是运行时目录，不提交；目录缺失时上传接口会自动创建。

4. WSL/Linux 构建

  • 仓库、node_modules 与构建输出均位于 WSL/Linux 原生文件系统，不位于 /mnt/c 或 /mnt/d。
  • node、npm、npx 均解析为 WSL 版本，不来自 Windows PATH。
  • 确认 .env 指向一次性构建数据库（推荐 file:./.tmp/build.db），不指向生产数据库。
  • 执行：
npm ci --no-audit --no-fund
npx tsc --noEmit
npm run lint
npm run audit:prod
npm run test:mp-contract
mkdir -p .tmp
npm run db:migrate:deploy
npm run build

  • 确认 npm run build 未隐式执行 migration、db:push 或 seed；上面的 db:migrate:deploy 只作用于一次性构建库。

  • 打包 .next/standalone、.next/static、public、prisma、prisma.config.ts、scripts。

5. 服务器发布

  • 停服务前已完成数据库和上传目录备份。
  • 新版本部署到 /var/www/alumni-site/app，旧版本保留为唯一的时间戳目录 /var/www/alumni-site/app.rollback-*。
  • /var/www/alumni-site/app/.env 软链接到 /var/www/alumni-site/.env。
  • /var/www/alumni-site/app/public/uploads 指向 /var/www/alumni-site/uploads。
  • 既有生产库首次纳管 migration 时，已在生产副本核对 schema diff，且差异只有预期增量。
  • 首次纳管时只将 20260710000000_baseline resolve 为 applied；未手工 resolve 任何增量 migration。
  • 常规发布显式执行 DATABASE_URL="file:/var/www/alumni-site/data/prod.db" npx prisma migrate deploy，并用 migrate status 确认完成；生产禁止 db push。
  • 如涉及身份字段清洗，先 dry-run，再正式执行。
  • 重启 alumni-site 后检查日志无持续 500 或启动错误。

6. 上线后验证

curl -s http://127.0.0.1:3000/api/health
curl -I https://yanchuaner.cn
sudo systemctl status alumni-site
sudo journalctl -u alumni-site -n 100 --no-pager

手动检查：

  • 首页和 /about 可公开访问。
  • 未登录访问 /news、/events、/students、/teachers、/contact、/alumni/* 会跳转登录。
  • 校友账号可访问校友空间，地图和统计有 Skeleton/加载态且移动端不溢出。
  • 管理员可访问 /admin，能查看统计、审核队列和主要 CRUD 页。
  • 后台上传图片后 /uploads/<文件名> 可访问。
  • 个人中心修改资料、故事投稿、基础身份修正申请流程正常。

7. 回滚条件

出现以下情况时优先回滚，而不是在线热修：

  • 登录、注册、校友认证、管理员后台大面积不可用。
  • 首页或主要校友页面静态资源 404，清缓存和重启仍不能恢复。
  • Prisma migration 后出现持续数据库错误。
  • 上传目录或生产数据库权限异常，影响后台发布内容。

回滚命令见 deployment.md。