feat(deploy): 添加环境配置模板 + 修复 compose 路径 bug #1628

Merged

xiaoxia merged 1 commits from feat/config-templates-phase2 into develop 2026-09-02 16:35:21 +08:00

Conversation 3 Commits 1 Files Changed 6

+576 -1

xiaoxia commented 2026-09-02 15:26:11 +08:00

Owner

Copy Link

Copy Source

变更内容

新增文件

1. deploy/configs/.env.staging — Staging 环境配置模板

   • 基于 .env.example，包含 MinIO 配置（Staging 独有）
   • 敏感值使用 ${PLACEHOLDER} 占位符标记
   • 包含 PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com
   • 包含 GENERATED_FILES_HOST_DIR=/var/lib/xiaoxia-saas-staging/generated
   • JWT 细项全部显式声明

2. deploy/configs/.env.production — Production 环境配置模板

   • 不包含 MinIO 配置（Production 用 OSS）
   • 不包含 PG/Redis 直连参数，统一走 DATABASE_URL 和 REDIS_URL
   • 包含 PUBLIC_API_BASE_URL=https://api.xiaoxiajianji.com
   • 包含 GENERATED_FILES_HOST_DIR=/var/lib/xiaoxia-saas-production/generated
   • JWT 细项全部显式声明

3. deploy/configs/nginx-staging.conf — Staging Nginx 配置

   • 代理到 xiaoxia-api-staging:8000

4. deploy/configs/nginx-production.conf — Production Nginx 配置

   • 代理到 xiaoxia-api-production:8000
   • 包含 assets legacy fallback

修复

• infra/docker/compose.yml — GENERATED_FILES_HOST_DIR 从 :- 默认值改为 :? 强制要求
  • 修复前：device: ${GENERATED_FILES_HOST_DIR:-/var/lib/xiaoxia-saas-staging/generated}（Production 缺省值时静默指向 staging）
  • 修复后：device: ${GENERATED_FILES_HOST_DIR:?GENERATED_FILES_HOST_DIR must be set in .env}（未设置则 docker compose 报错）

其他

• 更新 .gitignore：为 deploy/configs/ 下的模板文件添加例外规则

## 变更内容 ### 新增文件 1. **deploy/configs/.env.staging** — Staging 环境配置模板 - 基于 .env.example，包含 MinIO 配置（Staging 独有） - 敏感值使用 `${PLACEHOLDER}` 占位符标记 - 包含 `PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com` - 包含 `GENERATED_FILES_HOST_DIR=/var/lib/xiaoxia-saas-staging/generated` - JWT 细项全部显式声明 2. **deploy/configs/.env.production** — Production 环境配置模板 - 不包含 MinIO 配置（Production 用 OSS） - 不包含 PG/Redis 直连参数，统一走 DATABASE_URL 和 REDIS_URL - 包含 `PUBLIC_API_BASE_URL=https://api.xiaoxiajianji.com` - 包含 `GENERATED_FILES_HOST_DIR=/var/lib/xiaoxia-saas-production/generated` - JWT 细项全部显式声明 3. **deploy/configs/nginx-staging.conf** — Staging Nginx 配置 - 代理到 `xiaoxia-api-staging:8000` 4. **deploy/configs/nginx-production.conf** — Production Nginx 配置 - 代理到 `xiaoxia-api-production:8000` - 包含 assets legacy fallback ### 修复 - **infra/docker/compose.yml** — `GENERATED_FILES_HOST_DIR` 从 `:-` 默认值改为 `:?` 强制要求 - 修复前：`device: ${GENERATED_FILES_HOST_DIR:-/var/lib/xiaoxia-saas-staging/generated}`（Production 缺省值时静默指向 staging） - 修复后：`device: ${GENERATED_FILES_HOST_DIR:?GENERATED_FILES_HOST_DIR must be set in .env}`（未设置则 docker compose 报错） ### 其他 - 更新 `.gitignore`：为 `deploy/configs/` 下的模板文件添加例外规则

xiaoxia added 1 commit 2026-09-02 15:26:12 +08:00

feat(deploy): 添加环境配置模板 + 修复 compose 路径 bug ... 7eecabaf3d

- 新增 deploy/configs/.env.staging — Staging 环境配置模板（含 MinIO）
- 新增 deploy/configs/.env.production — Production 环境配置模板（无 MinIO）
- 新增 deploy/configs/nginx-staging.conf — Staging Nginx 配置
- 新增 deploy/configs/nginx-production.conf — Production Nginx 配置
- 修复 infra/docker/compose.yml: GENERATED_FILES_HOST_DIR 去掉默认值，
  改为 ?: 语法强制要求显式设置，防止 Production 静默指向 staging 目录
- 更新 .gitignore: 为 deploy/configs/ 下的模板文件添加例外

auto-approve-bot commented 2026-09-02 15:30:40 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：1 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [deploy/configs/nginx-production.conf:26 & deploy/configs/.env.production:26] API 服务端口配置不一致
   • 问题类型：逻辑bug
   • 问题描述：nginx-production.conf 中 proxy_pass 指向的后端服务端口为 8000，而在 .env.production 中定义的 API_PORT 为 8001。这会导致 Nginx 无法正确连接到后端 API 容器，造成生产环境 502 Bad Gateway 错误。
   • 修改建议：请统一端口配置。建议将 nginx-production.conf 中的端口修改为 8001，或者将 .env.production 中的端口修改为 8000，确保两者一致。

💡 改进建议（不阻塞合并）

1. [deploy/configs/nginx-production.conf:17-22] 缺少 index.html 的缓存控制头

   • 具体内容：Production 环境的 Nginx 配置中，注释提到“index.html 禁止缓存”，但实际配置块 location / 中并未设置 Cache-Control: no-cache 等响应头（对比 nginx-staging.conf 中有显式配置）。这可能导致浏览器或 CDN 缓存了旧的 HTML 文件，导致新版本发布后用户访问到旧版本页面（白屏或报错）。建议参考 Staging 配置，增加 location = /index.html 块并设置禁用缓存的头。

2. [.gitignore:27-28] 敏感文件提交风险

   • 具体内容：.gitignore 中使用了 !deploy/configs/.env.staging 和 !deploy/configs/.env.production 强制提交规则。虽然当前提交的文件内容均为占位符（如 ${DATABASE_URL}），但此规则允许未来包含真实密钥的文件被提交。建议配合 Git Hook（如 pre-commit）或 Secret Scanner 工具，防止误将真实密钥写入这两个文件并提交到仓库。

✅ 良好实践

• infra/docker/compose.yml 中使用了 ${GENERATED_FILES_HOST_DIR:?...} 语法，强制要求环境变量必须设置，避免了因变量缺失导致的默认路径挂载错误，增强了生产环境的安全性。
• 配置文件结构清晰，区分了 Production 和 Staging 环境，且对敏感信息使用了占位符替换机制，符合安全规范。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-09-02 07:30:40 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：1 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[deploy/configs/nginx-production.conf:26 & deploy/configs/.env.production:26] API 服务端口配置不一致** - 问题类型：逻辑bug - 问题描述：`nginx-production.conf` 中 `proxy_pass` 指向的后端服务端口为 `8000`，而在 `.env.production` 中定义的 `API_PORT` 为 `8001`。这会导致 Nginx 无法正确连接到后端 API 容器，造成生产环境 502 Bad Gateway 错误。 - 修改建议：请统一端口配置。建议将 `nginx-production.conf` 中的端口修改为 `8001`，或者将 `.env.production` 中的端口修改为 `8000`，确保两者一致。 ### 💡 改进建议（不阻塞合并） 1. **[deploy/configs/nginx-production.conf:17-22] 缺少 index.html 的缓存控制头** - 具体内容：Production 环境的 Nginx 配置中，注释提到“index.html 禁止缓存”，但实际配置块 `location /` 中并未设置 `Cache-Control: no-cache` 等响应头（对比 `nginx-staging.conf` 中有显式配置）。这可能导致浏览器或 CDN 缓存了旧的 HTML 文件，导致新版本发布后用户访问到旧版本页面（白屏或报错）。建议参考 Staging 配置，增加 `location = /index.html` 块并设置禁用缓存的头。 2. **[.gitignore:27-28] 敏感文件提交风险** - 具体内容：`.gitignore` 中使用了 `!deploy/configs/.env.staging` 和 `!deploy/configs/.env.production` 强制提交规则。虽然当前提交的文件内容均为占位符（如 `${DATABASE_URL}`），但此规则允许未来包含真实密钥的文件被提交。建议配合 Git Hook（如 pre-commit）或 Secret Scanner 工具，防止误将真实密钥写入这两个文件并提交到仓库。 ### ✅ 良好实践 - `infra/docker/compose.yml` 中使用了 `${GENERATED_FILES_HOST_DIR:?...}` 语法，强制要求环境变量必须设置，避免了因变量缺失导致的默认路径挂载错误，增强了生产环境的安全性。 - 配置文件结构清晰，区分了 Production 和 Staging 环境，且对敏感信息使用了占位符替换机制，符合安全规范。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-09-02 07:30:40 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

gitea-actions bot commented 2026-09-02 15:31:58 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1628
预览链接	https://pr-1628.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1628 | | 预览链接 | [https://pr-1628.preview.xiaoxiajianji.com](https://pr-1628.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia merged commit f098eabc12 into develop 2026-09-02 16:35:21 +08:00

xiaoxia deleted branch feat/config-templates-phase2 2026-09-02 16:35:21 +08:00

gitea-actions bot commented 2026-09-02 16:40:58 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1628 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1628 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1628