携岛文档

主题

前端开发/正式环境与正式蓝绿发布适配方案 ​

制定日期：2026-07-30
适用项目：App、AdminWeb、MerchantWeb、MerchantApp
状态：方案已确认，待分阶段实施

1. 目标 ​

本方案需要同时满足以下目标：

  1. 正式版用户始终使用稳定的正式域名，日常开发和测试不影响正式业务。
  2. 开发环境与测试环境合并为一套“开发验证环境”。
  3. 正式后端采用蓝绿发布：蓝色使用 8080，绿色使用 8081。
  4. 新版本可以先部署并验证，验证通过后再由 Nginx 平滑切换正式流量。
  5. 前端不感知蓝绿端口，蓝绿切换不要求重新构建或重新发布前端。

2. 最终环境拓扑 ​

环境/槽位API 域名后端端口数据库数据库账号
开发/测试https://dev-api.xiedao888.cn8082xiedao_devxiedao
正式蓝https://api.xiedao888.cn8080xiedao_prodxiedao_prod
正式绿https://api.xiedao888.cn8081xiedao_prodxiedao_prod

请求链路如下：

text
小程序正式版、正式 AdminWeb、正式 MerchantWeb
                         │
                         ▼
             https://api.xiedao888.cn
                         │
                         ▼
                       Nginx
                         │
               ┌─────────┴─────────┐
               ▼                   ▼
        正式蓝 127.0.0.1:8080  正式绿 127.0.0.1:8081
               │                   │
               └─────────┬─────────┘
                         ▼
                    xiedao_prod


小程序开发版/体验版、开发 AdminWeb、开发 MerchantWeb
                         │
                         ▼
           https://dev-api.xiedao888.cn
                         │
                         ▼
                开发/测试服务 8082
                         │
                         ▼
                     xiedao_dev

正式蓝、正式绿是同一正式环境的两个发布槽位，不是两套独立业务环境。两者必须共享正式数据库、正式 Redis、正式密钥及其他正式持久化资源。

开发/测试环境必须与正式环境隔离数据库、Redis 数据、日志、PID、上传临时目录以及外部服务开关。

3. 前端统一原则 ​

3.1 前端不配置蓝绿端口 ​

任何前端代码和构建配置都不应写入以下正式槽位地址：

text
http://服务器地址:8080
http://服务器地址:8081

正式前端只使用固定域名：

text
https://api.xiedao888.cn

当前正式流量进入蓝色还是绿色，完全由 Nginx 决定。

3.2 开发验证使用独立域名 ​

开发版、体验版和开发验证 Web 使用：

text
https://dev-api.xiedao888.cn

该域名由 Nginx 固定转发到 127.0.0.1:8082，不参与正式蓝绿切换。

3.3 不动态下发正式 API 地址 ​

正式小程序不通过远程配置动态获取 API 域名。正式 API 域名保持稳定，服务器、端口和蓝绿槽位的变化在 DNS/Nginx 后方完成。

这样可以避免远程配置不可用、配置被篡改、域名未加入微信白名单等风险。

4. 四个前端的适配要求 ​

4.1 App（用户端微信小程序） ​

当前配置文件：App/config/env.js

当前情况：

  • 正式地址已经是 https://api.xiedao888.cn。
  • 开发地址仍是局域网地址 http://192.168.1.68:8080。
  • 当前通过修改 currentEnv 手工切换环境，存在发布前忘记切换的风险。

目标调整：

  • 微信开发版 develop 使用 https://dev-api.xiedao888.cn。
  • 微信体验版 trial 使用 https://dev-api.xiedao888.cn。
  • 微信正式版 release 使用 https://api.xiedao888.cn。
  • 根据微信运行版本自动选择环境，取消日常手工切换。
  • 非微信运行环境（例如 Node.js 合约测试）默认选择开发环境，避免测试误请求正式接口。

建议逻辑：

js
function resolveEnvVersion() {
  if (typeof wx === 'undefined' || typeof wx.getAccountInfoSync !== 'function') {
    return 'develop'
  }
  return wx.getAccountInfoSync().miniProgram.envVersion || 'develop'
}

const currentEnv = resolveEnvVersion() === 'release'
  ? 'production'
  : 'development'

4.2 MerchantApp（商户端微信小程序） ​

当前配置文件：MerchantApp/config/env.js

当前情况和目标调整与 App 一致：

  • 替换局域网开发地址。
  • 开发版、体验版访问开发验证环境。
  • 正式版访问正式环境。
  • 根据 envVersion 自动选择环境。
  • 非微信测试运行环境默认选择开发环境。

两个小程序应采用相同的环境选择规则，避免一端自动切换、另一端继续手工切换。

4.3 AdminWeb（平台管理端） ​

涉及配置：

  • AdminWeb/.env.development
  • AdminWeb/.env.staging
  • AdminWeb/.env.production
  • AdminWeb/vite.config.js

当前正式配置已经使用 https://api.xiedao888.cn，蓝绿发布不需要修改正式 API 地址。

需要调整的部分：

  1. 将 Vite 开发代理目标从写死的 http://localhost:8080 改为环境变量，例如 VITE_DEV_PROXY_TARGET。
  2. 本地需要联调服务器开发环境时，将代理目标配置为 https://dev-api.xiedao888.cn。
  3. .env.staging 可以继续作为服务器开发验证构建配置，/stage-api 由开发验证站点的 Nginx 转发到 8082。
  4. 正式构建继续使用 .env.production，不增加 blue、green 两套前端构建模式。

AdminWeb 当前已经采用发布目录、符号链接原子切换、健康检查和失败回滚，可继续沿用现有部署方式。

部署入口及目录约定：

环境部署入口站点域名服务器目录构建模式
开发验证AdminWeb/deploy-dev.shhttps://dev-admin.xiedao888.cn/opt/xiedao/admin-devstaging
正式AdminWeb/deploy-prod.shhttps://admin.xiedao888.cn/opt/xiedao/adminproduction

两个环境分别维护发布目录、当前版本符号链接、部署锁和健康检查。首次发布开发验证版前，需要先按 Docs/nginx-xiedao888.cn.conf 中的 dev-admin.xiedao888.cn 站点配置 DNS。该开发站点与正式站点一样允许公网访问。

4.4 MerchantWeb（商户 Web 端） ​

涉及配置：

  • MerchantWeb/.env.development
  • MerchantWeb/.env.staging
  • MerchantWeb/.env.production
  • MerchantWeb/vite.config.js
  • MerchantWeb/deploy-dev.sh
  • MerchantWeb/deploy-prod.sh
  • MerchantWeb/deploy-remote.sh

环境配置调整与 AdminWeb 相同：

  1. 正式构建继续使用 https://api.xiedao888.cn。
  2. Vite 开发代理目标改为环境变量。
  3. 开发验证构建通过开发域名或 /stage-api 访问 8082。
  4. 不增加蓝色、绿色前端 API 地址。

MerchantWeb 采用与 AdminWeb 相同的发布目录、符号链接原子切换、健康检查和失败回滚机制。

部署入口及目录约定：

环境部署入口站点域名服务器目录构建模式
开发验证MerchantWeb/deploy-dev.shhttps://dev-merchant.xiedao888.cn/opt/xiedao/merchant-devstaging
正式MerchantWeb/deploy-prod.shhttps://merchant.xiedao888.cn/opt/xiedao/merchantproduction

两个环境分别维护发布目录、当前版本符号链接、部署锁和健康检查。首次发布开发验证版前，需要先按 Docs/nginx-xiedao888.cn.conf 中的 dev-merchant.xiedao888.cn 站点配置 DNS。该开发站点与正式站点一样允许公网访问。

5. 微信小程序平台配置 ​

两个小程序都需要在各自的微信公众平台中配置合法服务器域名。

至少检查以下类型：

  • request 合法域名
  • uploadFile 合法域名
  • downloadFile 合法域名
  • socket 合法域名（如果直接使用 WebSocket）

业务 API 域名至少包含：

text
https://api.xiedao888.cn
https://dev-api.xiedao888.cn

OpenIM 的 API/WebSocket 地址目前由后端凭证接口返回。若开发和正式使用不同 OpenIM 环境，相应地址也必须分别加入微信合法域名配置。

6. 正式蓝绿发布流程 ​

假设蓝色 8080 当前承载正式流量，新版本部署到绿色 8081：

  1. 在 8082 + xiedao_dev 完成功能开发、联调和完整测试。
  2. 构建正式候选后端并部署到绿色目录。
  3. 使用正式配置启动绿色服务，确认其连接 xiedao_prod 和正式 Redis。
  4. 在服务器本机或受限的内部验证入口进行绿色健康检查和只读冒烟验证。
  5. 保持 Nginx 正式 upstream 指向蓝色，绿色验证期间不接收正式用户流量。
  6. 运行 nginx -t 检查新配置。
  7. 将 upstream 从 127.0.0.1:8080 改为 127.0.0.1:8081。
  8. 执行 systemctl reload nginx 平滑加载配置。
  9. 通过正式域名验证核心接口、日志、数据库连接和错误率。
  10. 保留蓝色一段观察时间，稳定后再停止蓝色。
  11. 如绿色异常，将 upstream 改回蓝色并再次平滑加载 Nginx。

不能先停止蓝色再切换，否则会人为制造停机窗口。

7. 前后端发布兼容要求 ​

蓝绿切换只能保证流量平滑转移，不能自动解决版本不兼容问题。

正式绿色后端必须兼容：

  • 当前正式 AdminWeb。
  • 当前正式 MerchantWeb。
  • 已发布但尚未升级的历史小程序版本。
  • 浏览器缓存中仍在运行的旧前端资源。

涉及 API 或数据库结构变更时，应采用以下顺序：

  1. 先增加兼容字段或兼容接口，不立即删除旧能力。
  2. 部署并切换兼容新旧前端的后端版本。
  3. 再发布新版 Web 和小程序。
  4. 等待旧前端退出使用范围后，再单独清理旧字段和旧接口。

推荐发布顺序：

text
开发验证环境完整测试
        ↓
部署并验证正式绿色后端
        ↓
Nginx 切换正式后端流量
        ↓
发布新版 AdminWeb、MerchantWeb
        ↓
提交/发布新版 App、MerchantApp

8. 数据和运行资源隔离要求 ​

8.1 开发/测试与正式环境 ​

必须隔离：

  • MySQL schema：xiedao_dev 与 xiedao_prod。
  • 数据库账号：xiedao 与 xiedao_prod。
  • Redis Database 或键前缀。
  • JWT/缓存命名空间，避免开发令牌进入正式环境。
  • 应用日志和 PID 文件。
  • Quartz 调度器实例或调度开关。
  • 支付、退款、分账、短信等外部能力。

开发验证环境不得执行真实支付、真实退款、真实分账和真实短信发送。

8.2 正式蓝与正式绿 ​

正式蓝绿必须共享：

  • xiedao_prod。
  • 正式 Redis。
  • 正式 JWT/加密密钥。
  • OSS 等正式持久化资源。

蓝绿短时间同时运行时，必须避免 Quartz 任务重复执行。应使用可靠的集群调度/分布式锁，或在绿色接管流量前禁用其调度任务。

9. 同服务器部署的限制 ​

开发验证、正式蓝和正式绿虽然逻辑隔离，但仍共享服务器 CPU、内存、磁盘和网络。

为了降低开发环境影响正式环境的风险：

  • 开发验证环境不得执行压力测试。
  • 对开发服务设置合理的内存上限。
  • 避免在正式业务高峰期进行大型构建、数据导入和全表查询。
  • 启动绿色前先检查服务器剩余内存和磁盘空间。
  • 正式数据库迁移应评估锁表时间，并采用向后兼容变更。

如果未来要求更强的故障隔离，应将开发验证环境迁移到独立服务器或独立资源实例。

10. 实施清单 ​

域名和 Nginx ​

  • [ ] 创建并解析 dev-api.xiedao888.cn。
  • [ ] 配置 dev-api.xiedao888.cn -> 127.0.0.1:8082。
  • [ ] 创建并解析 dev-admin.xiedao888.cn 和 dev-merchant.xiedao888.cn。
  • [ ] 应用主 Nginx 配置中的开发 API 和两个开发 Web 公网站点。
  • [ ] 配置正式 API upstream 可在 8080 和 8081 之间单节点切换。
  • [ ] 确认 Nginx 使用平滑 reload，不使用停止后启动。
  • [ ] 绿色验证入口仅允许服务器本机或受信任来源访问。

App ​

  • [ ] 开发地址改为 https://dev-api.xiedao888.cn。
  • [ ] 根据 envVersion 自动选择开发/正式环境。
  • [ ] 增加非微信测试环境的安全回退。
  • [ ] 验证开发版、体验版和正式版请求目标。

MerchantApp ​

  • [ ] 开发地址改为 https://dev-api.xiedao888.cn。
  • [ ] 根据 envVersion 自动选择开发/正式环境。
  • [ ] 增加非微信测试环境的安全回退。
  • [ ] 验证开发版、体验版和正式版请求目标。

AdminWeb ​

  • [x] Vite 开发代理目标改为环境变量。
  • [x] 验证 build:prod 只访问正式 API 域名。
  • [x] 验证 build:stage 只访问开发验证环境。
  • [x] 保留现有原子部署和回滚机制。

MerchantWeb ​

  • [x] Vite 开发代理目标改为环境变量。
  • [x] 验证 build:prod 只访问正式 API 域名。
  • [x] 验证 build:stage 只访问开发验证环境。
  • [x] 将直接清空 dist 的部署方式改为发布目录加符号链接原子切换。
  • [x] 增加部署后健康检查和失败回滚。

11. 验收标准 ​

完成适配后必须满足：

  1. 微信开发版和体验版只能访问 dev-api.xiedao888.cn。
  2. 微信正式版只能访问 api.xiedao888.cn。
  3. 两个 Web 正式构建中不包含服务器 IP、8080 或 8081 地址。
  4. 两个 Web 开发验证构建不会访问正式 API。
  5. 开发验证环境的数据库连接均指向 xiedao_dev。
  6. 正式蓝绿的数据库连接均指向 xiedao_prod。
  7. Nginx 在蓝绿切换过程中不停止服务。
  8. 绿色未切流量前，正式用户请求仍全部进入蓝色。
  9. 切换失败时可以通过修改 upstream 并重新加载 Nginx快速回滚。
  10. 旧 Web 资源和旧小程序版本在正式后端切换后仍可正常使用。

12. 与旧部署设计的关系 ​

Docs/superpowers/specs/2026-06-30-deployment-and-versioning-design.md 中曾将 8081 规划为测试环境端口。该端口规划已被本方案替代：

text
旧规划：正式 8080，测试 8081
新规划：正式蓝 8080，正式绿 8081，开发/测试 8082

后续实施环境适配和蓝绿发布时，以本文件的端口及域名规划为准。

13. 当前状态说明 ​

截至 2026-07-30：

  • xiedao_prod 已创建，但尚未迁移开发数据。
  • 当前服务器上的 Java 服务仍连接 xiedao_dev。
  • 当前运行服务尚不能视为已完成配置的“正式蓝”。
  • 本方案文档不授权提前切换数据库或重启线上服务。
  • 应先完成配置、目录、域名和部署脚本适配，再单独安排数据迁移及首次正式切换。

携岛 XieDao · 内部文档

功能与使用文档以仓库 Docs/ 目录下的 Markdown 源文件为准