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/statusHTTP 健康检查,运行时声明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,提供三项能力:- 自动加载
$CONFIG_DIR/.env:容器启动时若检测到该文件,自动作为--env <path>参数传入 one-api-pro,用户挂载.env即可生效,无需修改docker run命令; - 透传用户 CLI 参数:
docker run image --port 8080 --log-dir /xxx这类参数会被原样转发到 one-api-pro; - 调试模式直通:当 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 apiPATCH/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拉取新镜像并重启。