# Ubuntu 源码生产部署

这是项目唯一生产部署方式，支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS x86_64。服务器管理员预先提供 Node.js 22.x、pnpm 10.25.0、Nginx，以及外部 MySQL 5.7.x、Redis、RocketMQ 5.x；项目不负责安装、升级、启动、停止、删除或修改这些系统软件与服务。

## 构建发布目录

在固定提交的干净工作区执行：

```bash
uname -m
node --version
pnpm --version
pnpm install --frozen-lockfile
pnpm verify:release
```

架构必须为 `x86_64`，Node.js 必须为 22.x，pnpm 必须为 10.25.0。发布门禁会完成测试、Web/Server 构建、双视口浏览器检查，并核对 Web、API、Scheduler、Worker 产物与 systemd/Nginx 模板。

每次发布使用 `/opt/a-share-analysis/releases/<版本或提交>/` 新目录。完整传输并验证目录后，再把 `/opt/a-share-analysis/current` 原子切换到目标目录；禁止在 `current` 中原地覆盖文件，也禁止只发布部分进程产物。

## 配置与 systemd

生产配置放在 `/etc/a-share-analysis/api.env`、`scheduler.env`、`worker.env`，建议权限 `root:a-share 0640`；Web 的 `VITE_` 公开变量在构建前注入。三个 systemd 单元通过各自的 `EnvironmentFile=` 只读取本进程需要的键，运行用户为非登录系统用户 `a-share`。

```bash
sudo install -m 0644 deploy/systemd/a-share-api.service.example /etc/systemd/system/a-share-api.service
sudo install -m 0644 deploy/systemd/a-share-scheduler.service.example /etc/systemd/system/a-share-scheduler.service
sudo install -m 0644 deploy/systemd/a-share-worker.service.example /etc/systemd/system/a-share-worker.service
sudo install -m 0644 deploy/nginx/a-share-analysis.conf.example /etc/nginx/conf.d/a-share-analysis.conf
sudo systemd-analyze verify /etc/systemd/system/a-share-api.service
sudo systemd-analyze verify /etc/systemd/system/a-share-scheduler.service
sudo systemd-analyze verify /etc/systemd/system/a-share-worker.service
sudo nginx -t
sudo systemctl daemon-reload
sudo systemctl restart a-share-api.service
sudo systemctl restart a-share-scheduler.service
sudo systemctl restart a-share-worker.service
sudo systemctl status a-share-api.service a-share-scheduler.service a-share-worker.service
sudo journalctl -u a-share-api.service -u a-share-scheduler.service -u a-share-worker.service --since '5 minutes ago'
curl --fail http://127.0.0.1:3000/api/v1/health
curl --fail http://127.0.0.1/
```

当前工程尚无业务表迁移；后续新增迁移后必须在切换 `current` 前单独执行并记录结果。生产环境禁止 `synchronize: true`，开发流程也禁止用生产数据库做 Schema 基线或连接测试。

## AKTools 生产边界

AKTools 不随本项目发布，也不由 systemd 单元管理。生产 API 默认关闭 `AKTOOLS_ENABLED`；只有在 AKTools 以受控内网服务部署、完成访问控制、授权和稳定性评估后，才可在 API 的生产环境文件中启用。生产配置不得把 AKTools 地址暴露给浏览器，且必须同步修改服务端白名单和健康检查方案；未完成这些前置条件时保持短线模块 `unavailable`。

## 检查与回退

使用 `systemctl status`、`journalctl -u`、HTTP 健康端点和 Nginx 同源访问结果确认发布。任一验证失败时，把 `/opt/a-share-analysis/current` 原子切回上一完整发布目录，重启三个 systemd 服务并重复健康检查。

`/etc/a-share-analysis/*.env` 和外部 Redis、MySQL、RocketMQ 数据不随应用目录切换而覆盖或删除。RocketMQ 的 NameServer、Broker、Proxy 与 CommitLog 由运维独立维护。