# Ubuntu 源码生产部署

正式支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS 的 x86_64。服务器管理员预先提供 Node.js 22 LTS、pnpm 10、Nginx，以及 MySQL 5.7、Redis、RocketMQ 5.x 或相应外部服务；项目不负责安装或升级这些软件，也不修改系统软件源。

## 前置验证

```bash
uname -m
node --version
pnpm --version
nginx -v
```

架构必须为 `x86_64`，Node.js 必须为 22 LTS，pnpm 必须为 10.x。不满足要求时终止部署。

## 目录与配置

- 发布目录：`/opt/a-share-analysis/releases/<版本或提交>/`。
- 当前版本：`/opt/a-share-analysis/current` 符号链接。
- 生产配置：`/etc/a-share-analysis/api.env`、`scheduler.env`、`worker.env`、`web.env`。
- 运行用户：非登录系统用户 `a-share`。

真实配置从仓库生产模板生成，但不得放入发布目录。API、Scheduler、Worker 的 systemd 单元分别通过 `EnvironmentFile=` 读取自己的配置；包含秘密的文件建议为 `root:a-share 0640`。

## 构建与启动边界

使用 `pnpm install --frozen-lockfile` 安装锁定依赖，在新发布目录构建 Web 和 Server。Web 静态文件由 Nginx 托管，API、Scheduler、Worker 运行编译后的 JavaScript。禁止 Vite 开发服务器、watch、调试端口和生产运行 TypeScript。

当前应用尚未脚手架化，仓库中的 systemd 与 Nginx 文件是路径和权限契约示例，不能冒充已经验证的线上启动文件。后续应用功能必须补充实际构建、启动和健康检查验证。

## 升级、检查与回退

在新的不可变发布目录完成安装、构建和配置校验后，原子切换 `current`，依次重启 API、Scheduler、Worker 并检查 `systemctl status`、`journalctl` 和 HTTP 健康端点。失败时切回上一完整目录并重启服务；生产配置不随版本切换覆盖。

项目部署流程禁止连接或读取生产数据库做开发验证。数据库备份属于独立运维职责，应用回退不得删除或覆盖数据。

RocketMQ 由运维独立维护 NameServer、Broker 和需要时的 Proxy。应用发布只读取受控的 RocketMQ Endpoint、Topic 前缀与 Group 配置，不负责创建或升级集群，也不得把 Broker 数据目录放进应用发布目录。