背景

  • 服务：lover-api

  • 服务器目录：/opt/lover_team/backend

  • 启动方式：systemd

  • 依赖：PostgreSQL、Redis（由 1Panel 安装，容器运行）

本次关键结论

  • 本地构建必须显式指定 GOOS=linux，否则会误上传 Windows 可执行导致 Exec format error。

  • prod.yaml 可以不存密码，生产密码通过 systemd Environment 注入即可。

  • 启动配置依赖 APP_CONFIG，需使用绝对路径（例如 /opt/lover_team/backend/configs/prod.yaml）。

  • 1Panel 安装 Redis 后，宿主机不一定有 redis-cli 命令，这是正常现象；可通过容器内执行验证。

本次踩坑与修复

  1. 二进制格式错误

  • 现象：服务启动失败，报可执行格式异常。

  • 原因：上传了 Windows 二进制。

  • 修复：本地改为 GOOS=linux GOARCH=amd64 重新构建。

  1. 配置文件找不到

  • 现象：open backend/configs/dev.yaml: no such file or directory。

  • 原因：未正确指定 APP_CONFIG，默认相对路径在服务器上不成立。

  • 修复：systemd 增加 Environment=APP_CONFIG=/opt/lover_team/backend/configs/prod.yaml。

  1. PostgreSQL 认证失败

  • 现象：password authentication failed for user postgres database postgres。

  • 原因：systemd 中配置的 PG_PASSWORD 与数据库实际密码不一致。

  • 修复：统一 PG_PASSWORD 与 PostgreSQL 密码，并重启服务。

  1. exchange 返回 50003

  • 现象：/api/v1/auth/exchange 报 50003（identity persist failed）。

  • 原因：发布时只替换了二进制，未同步 migrations/ 目录，需求02表结构未创建。

  • 修复：上传 /opt/lover_team/backend/migrations 并重启服务触发自动迁移。

  1. 迁移目录路径认知偏差

  • 现象：误以为二进制位于 backend 目录就一定能找到 migrations。

  • 原因：migration_dir: migrations 是相对路径，实际相对 systemd WorkingDirectory，不是相对二进制文件路径。

  • 修复：保证 WorkingDirectory=/opt/lover_team/backend 且 migrations 在该目录下；或直接将 migration_dir 改为绝对路径。

推荐发布顺序（后续复用）

  1. Windows 本地测试与 Linux 构建。

  1. 生成 lover-api-linux-amd64.tar.gz 并上传服务器。

  1. 校验 systemd 环境变量（特别是 APP_CONFIG、PG_PASSWORD、AUTH_ACCESS_SECRET）。

  1. 备份旧二进制、覆盖新二进制、重启服务。

  1. 验证 health/version、迁移版本、日志与公网访问。

发布物清单（需求02起）

  • 必需：lover-api。

  • 必需：configs/prod.yaml（及本地环境覆盖项）。

  • 必需：migrations/（至少包含 0001、0002、0003）。

  • 建议：发布后第一时间检查 schema_migrations 与 audit_logs 写入是否正常。

验收重点

  • health 返回 code=0 且 db=up、redis=up。

  • schema_migrations 包含 0002_req02_identity_sessions.sql、0003_req02_table_comments.sql。

  • Swagger 可访问，登录/刷新链路可用，旧 refresh token 重放返回 40103。