# 开发、生产环境与双部署方式设计规格

- 功能编号：GOV-006
- 规格版本：0.1
- 状态：approved_for_review
- 日期：2026-08-13

## 背景与目标

项目已经明确前后端和基础设施技术栈，但目前只有 `.gitignore` 排除 `.env`，没有正式的开发/生产配置契约、模板结构、加载优先级和部署边界。缺少这些规则会导致本地开发误用生产配置、生产回退到模拟数据、不同部署方式使用不同变量，以及密钥进入仓库或构建产物。

本功能建立统一的环境配置体系，并同时支持 Docker Compose 与 Ubuntu 源码生产部署。两种生产方式必须使用相同变量名、配置校验、进程边界和发布版本，不允许形成两套行为不同的应用。

## 环境模型

项目只定义两个应用运行环境：

- `development`：本地开发、热更新、确定性模拟数据和开发 Redis。
- `production`：线上运行，禁止热更新、调试端口、模拟数据和开发默认值回退。

测试运行使用测试工具自己的隔离配置，不把 `test` 作为可部署环境。应用启动必须显式获得环境值；生产环境缺少配置或出现非法组合时立即退出，不能静默使用开发默认值。

业务代码不得到处分支判断环境。环境差异在配置加载、依赖注入和基础设施 Adapter 边界收敛，纯业务计算保持一致。

## 仓库模板结构

仓库提交完整但不含秘密的模板：

```text
deploy/env/
├── development/
│   ├── api.env.example
│   ├── scheduler.env.example
│   ├── worker.env.example
│   └── web.env.example
└── production/
    ├── api.env.example
    ├── scheduler.env.example
    ├── worker.env.example
    └── web.env.example
```

每个模板必须为每项变量写明用途、示例格式、是否必填、敏感性和启用条件。密码、Token 和 API Key 使用空值，不使用看似真实的占位凭据。

真实开发配置使用同目录或项目约定位置的 `*.env.local`，由 Git 忽略。真实生产配置永远不放在仓库、发布目录、镜像层或前端构建产物中。

## 配置契约与校验

API、Scheduler、Worker 使用独立 Schema 校验各自配置，遵守最小知情范围：

- API：HTTP 监听、Redis、当前快照、按需历史读取和 AI 调用配置。
- Scheduler：时区、交易日调度、Redis 分布式锁；RabbitMQ 未启用时使用服务内调度 Adapter。
- Worker：数据源、Redis、分析配置；未来启用时增加 MySQL、RabbitMQ 和 AI 变量。
- Web：只允许公开的 `VITE_*` 构建变量，例如 API 相对路径和应用标题。

功能开关控制条件必填：MySQL、RabbitMQ、正式数据源或 AI 未启用时，其连接变量可以为空；一旦开关启用，相关变量缺失、格式错误或不安全时必须拒绝启动。

前端构建环境变量会进入浏览器代码，任何数据库、Redis、RabbitMQ、数据源或 AI 凭据都不得使用 `VITE_*` 前缀。

## 本地开发方式

本地开发默认使用 Docker Compose 只启动 Redis。Web、API、Scheduler 和 Worker 直接从源码运行，使用热更新和开发配置，便于调试。

第一阶段不启动 MySQL 和 RabbitMQ：

- MySQL 只定义 Repository 接口并使用内存实现。
- RabbitMQ 只定义消息契约和发布接口，Scheduler 通过服务内 Adapter 调用任务。
- Redis 是第一阶段唯一实际启用的外部基础设施，用于当前快照、缓存、刷新锁和调度锁。

开发 Compose 文件不得加载生产配置，不得连接生产地址。开发服务名、网络和数据目录必须使用项目专用前缀，避免影响其他项目。

## Docker Compose 生产部署

生产 Compose 支持运行 Web/Nginx、API、Scheduler、Worker，以及按部署选择连接内部或外部 Redis、MySQL 5.7 和 RabbitMQ。第一阶段未启用的组件不应为了形式完整而启动。

要求：

- 镜像对应明确 Git 提交或版本标签，禁止使用浮动 `latest` 作为可回退版本。
- 使用外部指定的生产 env 文件加载同一配置契约，不把秘密写入 Compose YAML。
- 禁止源码挂载、热更新、调试端口和开发命令。
- 服务提供健康检查、日志边界、启动顺序和优雅停止。
- 数据目录使用明确宿主机路径或经确认的持久化方案，升级不得删除数据。

## Ubuntu 源码生产部署

正式支持平台：

- Ubuntu 22.04 LTS x86_64。
- Ubuntu 24.04 LTS x86_64。

服务器管理员预先提供并维护：

- Node.js 22 LTS。
- pnpm 10。
- Nginx。
- MySQL 5.7、Redis、RabbitMQ 或对应外部服务。

项目只验证版本和连通性，不修改软件源，不安装或升级 Node.js、pnpm、Nginx、MySQL、Redis 或 RabbitMQ。版本不符合要求时部署立即终止并给出明确错误。

依赖安装必须使用 `pnpm install --frozen-lockfile`。Web 构建为静态文件后由 Nginx 托管；API、Scheduler 和 Worker 运行编译后的 JavaScript，禁止在生产运行 TypeScript、Vite 开发服务器、Nest watch 或源码热更新。

## systemd 与生产配置位置

源码部署使用单个非登录系统用户 `a-share` 运行 API、Scheduler 和 Worker。第一阶段先降低部署复杂度，但仍把配置拆为独立文件，为以后按进程拆系统用户保留边界。

生产配置固定存放在发布目录之外：

```text
/etc/a-share-analysis/
├── api.env
├── scheduler.env
├── worker.env
└── web.env
```

systemd 单元通过 `EnvironmentFile=/etc/a-share-analysis/<进程>.env` 在启动时注入变量。切换 `/opt/a-share-analysis/current` 指向的应用版本不会覆盖配置。

API、Scheduler 和 Worker 分别只引用自己的 env 文件。第一阶段文件所有者为 `root:a-share`，包含秘密的文件权限为 `0640`；Web 配置只含公开构建变量，可由部署构建步骤读取。未来接入高价值数据源和 AI 密钥时，评估拆分独立系统用户和更细的文件组权限。

## 发布目录与进程边界

源码部署建议使用不可变版本目录：

```text
/opt/a-share-analysis/
├── releases/<版本或提交>/
└── current -> releases/<当前版本>/
```

更新时先在新目录安装、构建和校验，再原子切换 `current` 并重启服务。回退切回上一完整版本，不在旧目录上覆盖文件。

Nginx 托管当前版本 Web 静态产物并反向代理 API。API、Scheduler、Worker 为独立 systemd 服务；任一后台进程异常不得由 API 请求临时替代执行全市场采集任务。

## MySQL 兼容约束

两种部署方式和两个环境都受 GOV-005 约束：MySQL 固定 5.7.x，字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`。项目启动或迁移必须验证该条件，不得在开发环境使用 8.x 再假设向下兼容。

第一阶段 MySQL 未启用，因此配置模板保留功能开关和条件变量，但默认不连接数据库。

## 安全与防误用

- `.env`、`.env.*` 和 `*.env.local` 默认忽略，只允许提交 `*.env.example`。
- 模板、日志、错误和诊断输出不得包含真实秘密。
- 生产启动必须检查 `APP_ENV=production`，并拒绝模拟数据、开发 URL、调试模式和空的已启用服务凭据。
- 开发配置不得包含或连接生产主机；项目脚本禁止读取生产数据库进行开发验证。
- Docker Compose 与源码部署使用相同变量名称和 Schema，不用环境专属别名隐藏差异。
- Web 配置仅含公开值；所有付费 AI 和数据源密钥只存在服务端配置。

## 运维文档范围

两种生产部署方式都必须提供：

- 前置条件和版本检查。
- 初次部署、配置填充、构建和启动步骤。
- 健康检查、日志读取和进程状态检查。
- 使用确定版本的升级流程。
- 配置不变的应用回退流程。
- 数据服务备份职责声明和故障边界。

源码部署文档不提供基础设施安装脚本。Docker Compose 文档不能暗示其配置可以直接用于本地开发。

## 实施范围

GOV-006 建立环境规范、变量模板、开发 Redis Compose、生产部署骨架、systemd/Nginx 示例及验证脚本的设计与追溯基础。由于 Web、Server、Scheduler 和 Worker 尚未实现，当前可先提供结构完整的模板和部署规范；具体应用启动命令在相应项目脚手架落地后通过后续功能验证，不得伪造已可运行状态。

## 验收标准

- 仓库包含开发与生产环境下 API、Scheduler、Worker、Web 的八份无秘密模板。
- 本地开发仅通过 Compose 启动项目专用 Redis，应用从源码运行。
- 生产同时有 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署规范。
- 源码部署明确管理员提供 Node.js 22 LTS、pnpm 10、Nginx 和基础设施，项目只验证不安装。
- 源码部署明确单个 `a-share` 用户、独立 EnvironmentFile 和发布目录边界。
- Docker Compose 与源码部署共用配置变量和校验规则。
- 生产环境无法回退到模拟数据、开发默认值、热更新或调试配置。
- MySQL 条件配置符合 GOV-005，第一阶段默认不启用 MySQL 和 RabbitMQ。
- 治理测试、模板静态检查、敏感信息检查、GitNexus 变更检测和双 Review 通过。
- 中文提交和对应版本标签精确推送到 Gitea。