Skip to content

v0.0.10 — Docker 镜像发布能力 ​

新增官方 Docker 镜像构建与发布能力:每次推送形如 v*.*.* 的 tag 时,自动构建并推送多架构(linux/amd64 + linux/arm64)镜像到 GitHub Container Registry;提供 docker run 一键部署、约定挂载目录 /app/config + /app/data、自动加载 .env 文件,并支持通过 CLI 参数自定义启动行为。

中文 ​

✨ 新增功能 ​

官方 Docker 镜像 ​

  • 新增根目录 Dockerfile,采用三阶段多阶段构建:
    • 阶段一使用 node:20-alpine 构建 web/default-pro 前端;
    • 阶段二使用 golang:1.22-alpine,CGO_ENABLED=0 静态编译 Go 二进制(项目使用 glebarez/sqlite 纯 Go 实现,无需 CGO),并自动下载 go.mod 声明的 1.25 toolchain;
    • 阶段三以 alpine:latest 为运行时基础镜像,仅安装 ca-certificates、tzdata、wget,体积小、安全性高。
  • 默认以非 root 用户 app 运行,内置 /api/status HTTP 健康检查,运行时声明 VOLUME [/app/config, /app/data]。
  • 默认环境变量:PORT=3000、LOG_DIR=/app/data/logs、SQLITE_PATH=/app/data/one-api-pro.db、CONFIG_DIR=/app/config。

智能启动入口(docker-entrypoint.sh) ​

  • 新增 docker-entrypoint.sh,作为容器 ENTRYPOINT,提供三项能力:
    1. 自动加载 $CONFIG_DIR/.env:容器启动时若检测到该文件,自动作为 --env <path> 参数传入 one-api-pro,用户挂载 .env 即可生效,无需修改 docker run 命令;
    2. 透传用户 CLI 参数:docker run image --port 8080 --log-dir /xxx 这类参数会被原样转发到 one-api-pro;
    3. 调试模式直通:当 CMD 首参既不是 one-api-pro 也不是其绝对路径时(例如 docker run image bash),入口直接 exec 透传给用户命令,方便进 shell 排查。
  • 使用 exec 替换当前进程,保证 SIGTERM 等信号正确传递到 one-api-pro。

🔧 工程 ​

  • 新增 .github/workflows/release-docker.yml,与现有 release.yml(二进制发布)解耦:
    • 触发条件:push 推送形如 v*.*.* 的 tag,或手动 workflow_dispatch(支持手动指定 tag);
    • 强制校验 CHANGELOG/<tag>.md 存在,与 release.yml 保持一致的发布流程;
    • 通过 docker/setup-qemu-action + docker/setup-buildx-action 启用多架构构建,linux/amd64 + linux/arm64 并行出图;
    • 使用 docker/metadata-action 自动生成 semver tag(:0.0.10、:0.0、:0),latest=auto 策略自动跳过预发布后缀(-rc / -beta 等);
    • 注入 OCI 元数据:org.opencontainers.image.{title,description,source,licenses,revision,created};
    • 启用 GHA 层缓存(cache-from: type=gha / cache-to: type=gha,mode=max),后续构建秒级复用;
    • 通过 ${{ secrets.GITHUB_TOKEN }} 直接登录 ghcr.io(无需额外配置 PAT);
    • 构建结束后调用 gh api PATCH /users/{owner}/packages/container/{repo} 或 /orgs/{owner}/packages/container/{repo},自动把包设为 public,continue-on-error: true 保证权限受限时不影响镜像推送。
  • 新增 .dockerignore:与 .gitignore 对齐,排除 .git、.github、node_modules、dist、logs、*.db、web/air、web/berry、web/default 等已废弃主题与构建产物。

📚 文档 ​

  • 在 README.md 新增「🐳 Docker 部署」章节,位于「手动部署」与「多机部署」之间,包含:
    • 镜像地址表(latest / 指定版本 / 大版本);
    • 挂载目录约定(/app/config 配置 + /app/data 数据);
    • 快速开始(SQLite 单文件)、.env 配置示例;
    • 切换 MySQL / PostgreSQL(SQL_DSN)、修改端口的三种等价方式(-e / .env / CLI 参数);
    • 全部 CLI 参数表(--port、--log-dir、--env、--version、--help);
    • docker-compose.yml 完整示例、调试模式(进 shell)、升级流程。

⚠️ 升级注意事项 ​

  • 本次为纯工程 / CI / 文档变更,无后端代码改动,无数据库迁移,可直接升级。
  • 现有二进制用户完全不受影响:未升级到 Docker 部署方式的二进制部署流程与之前一致。
  • 首次发布 Docker 镜像后请到 GitHub 仓库的 Packages 页面确认包已设为 public(CI 会自动尝试,少数组织仓库可能需要管理员手动确认)。
  • 若使用 docker-compose,请使用 docker compose pull && docker compose up -d 拉取新镜像并重启。