xiaoxia-saas/docs/DEPLOYMENT.md

部署说明

唯一部署入口

小虾 SaaS 当前唯一有效 Docker 部署入口是：

• infra/docker/compose.yml
• infra/docker/api.Dockerfile
• infra/docker/worker.Dockerfile
• infra/docker/web.Dockerfile
• infra/docker/deploy-staging.sh

仓库根目录的 Dockerfile 和 docker-compose.yml 已废弃，只作为防误用哨兵保留，不允许用于部署。

---

环境加载规则

开发环境

• 默认读取 .env
• 没有 .env 时回退到代码默认值

Staging

• 服务器环境文件：/var/lib/xiaoxia-saas-staging/.env
• APP_ENV=staging
• WEB_PORT=3001
• 由 Gitea Actions 调用 infra/docker/deploy-staging.sh

Production

• 生产环境文件：/var/lib/xiaoxia-saas-production/.env
• APP_ENV=production
• 只允许通过 tag/release 触发生产部署
• 必须替换所有密钥和 CHANGE_ME 项

---

本地/手动部署

从仓库根目录执行：

docker compose -f infra/docker/compose.yml up -d --build

Staging 手动部署应复用同一入口：

cp /var/lib/xiaoxia-saas-staging/.env .env
WEB_PORT=3001 docker compose -f infra/docker/compose.yml up -d --build

服务器自动部署使用：

infra/docker/deploy-staging.sh

部署脚本会在服务启动前执行 Alembic：

• 已存在 alembic_version 时执行 alembic upgrade head
• 已存在业务表但缺少 alembic_version 时执行 alembic stamp head && alembic upgrade head
• 空库时执行 alembic upgrade head

staging 已在 2026-06-21 验证：alembic_version = 002，健康检查通过。

---

外部服务配置

认证邮件和 session 存储为配置驱动：

• ENABLE_EMAIL_DELIVERY=false 时使用 no-op 邮件服务，不对外发送邮件。
• ENABLE_EMAIL_DELIVERY=true 时必须配置 SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD、SMTP_FROM_EMAIL、SMTP_FROM_NAME、SMTP_USE_TLS。
• ENABLE_REDIS_SESSIONS=false 时登录不会写 Redis session，JWT 仍可用于当前认证链路。
• ENABLE_REDIS_SESSIONS=true 时通过 REDIS_URL 创建 Redis session store。

Staging 当前可以保持 no-op；Production 开启前必须先验证 SMTP/Redis 连接和密钥。

---

Gitea Actions 约定

• develop 分支触发 staging 部署。
• tag v* 才允许触发 production 部署。
• Actions 先同步代码到 /var/lib/xiaoxia-saas-staging/repo。
• Actions 再复制 /var/lib/xiaoxia-saas-staging/.env 到部署工作目录。
• Actions 最终调用 infra/docker/deploy-staging.sh。

---

注意事项

• 不要使用根目录 Dockerfile。
• 不要使用根目录 docker-compose.yml。
• .env.production 不要提交真实密钥。
• OSS、数据库、Redis、JWT 密钥必须通过服务器环境文件注入。
• 生产环境必须设置 DEBUG=false。
• staging / production 不允许开启 AUTO_CREATE_SCHEMA 绕过 Alembic。