部署与运行

用户可见的安装和日常操作以根 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：

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 映射。

升级应使用：

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。

3.3 KiB Raw Permalink Blame History Unescape Escape