# 部署与运行

用户可见的安装和日常操作以根 [`README.md`](../../README.md) 为准；本文记录维护代码时必须理解的构建和数据边界。

## 镜像结构

`Dockerfile` 有三个阶段：Node 24.19.0 构建 React 静态资源；Go 1.26.0 以 `CGO_ENABLED=0` 构建后端；最终 Debian bookworm 镜像只包含 CA、时区和后端二进制，不再包含 Node runtime 或 Codex CLI。`APP_VERSION` 构建参数通过 Go linker 注入状态 API，未指定时默认为 `0.3.0`，前端在品牌区域显示该版本。

前端产物复制到 `backend/internal/web/dist` 后嵌入二进制。运行层使用 UID `10001` 的 system 用户 `helper`，默认 `DATA_DIR=/data`、`LISTEN_ADDR=:8080`，并暴露 `/data` volume 和 8080。健康检查调用二进制自身的 `healthcheck` 子命令。

## 发布镜像

仓库根目录的 `push-image.sh` 构建 `linux/amd64`、`linux/arm64` 镜像并推送至 Docker Hub。版本号必须形如 `0.3.0` 或 `0.3.0-beta.1`，同时作为应用版本和镜像标签；脚本还会更新 `latest`：

```bash
docker login -u koalalove
bash push-image.sh 0.3.0
# 完整重新构建：bash push-image.sh 0.3.0 --no-cache
```

脚本会创建并选用 `codex-helper-builder` buildx builder，并尝试通过 `tonistiigi/binfmt` 注册跨架构模拟器。发布前应先完成本地镜像验证；脚本执行成功即会推送远端标签。

## Compose 与持久化

`docker-compose.yml` 本地构建 `codex-helper:latest`，将宿主机 8180 映射到容器 8080，并把命名卷 `codex-helper-data` 挂载到 `/data`。该卷保存数据库和通知解密密钥；Codex OAuth 凭据由外部 CLIProxyAPI 保存。Compose 通过 `CLIPROXY_API_BASE_URL` 和 `CLIPROXY_API_MANAGEMENT_KEY` 注入 CPA Management API 配置，并为宿主机 CPA 提供 `host.docker.internal` 映射。

升级应使用：

```bash
git pull --ff-only
docker compose up -d --build
```

不要使用 `docker compose down -v`，也不要在未确认 volume 名和备份前重建、迁移或删除数据卷。需要改变运行 UID、volume 或 `DATA_DIR` 时，必须提供旧数据权限和路径的升级验证。

## 网络与安全

应用自身监听 HTTP。公网部署应放在 HTTPS 反向代理后，初始化前限制访问来源，并保证到 CLIProxyAPI、Telegram Bot API 和所选 SMTP 服务的出站连接。CPA 自身负责访问 ChatGPT Codex 服务。通用和通知配置由前端保存到数据库；CPA 根地址和 management key 只通过环境变量提供。

`CLIPROXY_API_MANAGEMENT_KEY` 不得写入镜像、Compose 明文仓库配置、日志或前端。Codex Helper 从独立容器访问 CPA 时，CPA 必须启用带 secret key 的 Management API，并允许来自该容器网络的远程管理请求。只开放必要网络路径，不应把 CPA Management API 直接暴露到公网。

## 备份与恢复

维护接口下载的 SQLite 快照适合查看或数据库级备份，但不包含解密密钥，也不包含外部 CPA 的 Codex 凭据。Codex Helper 恢复步骤是：停止容器、备份或恢复整个 `/data`、确认 UID `10001` 可读写、恢复正确的 CPA 环境变量，再启动并检查 `/health/live`、`/health/ready`、管理员登录和各账号连接。CLIProxyAPI 需要按其自身机制单独备份和恢复。恢复过程不得只替换数据库而遗失对应 `secret.key`。