178 lines
9.3 KiB
Markdown
178 lines
9.3 KiB
Markdown
# 开发、生产环境与双部署方式设计规格
|
||
|
||
- 功能编号：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。
|