CI/CD 与发布

仓库现在包含两条 GitHub Actions 流水线：

• docs.yml：构建并部署 VitePress 官网到 GitHub Pages
• docker.yml：测试、构建 services/opentransd 多架构 Docker 镜像并推送到 Docker Hub

文档官网发布

触发条件：

• push 到 main
• pull request 到 main 时只做构建校验
• 手动触发 workflow_dispatch

发布前需要在 GitHub 仓库里启用：

1. Settings -> Pages
2. Build and deployment -> Source 选择 GitHub Actions

如果你使用的是自定义域名，而不是 https://<owner>.github.io/<repo>/ 这种仓库子路径形式，还需要再配置一个 Repository Variable：

• DOCS_BASE=/

如果你希望把域名也和工作流配置绑定在一起，还可以额外配置：

• PAGES_CUSTOM_DOMAIN=your.domain.com

如果仓库里已经提交了 website/public/CNAME，工作流也会自动按根路径 / 构建；当前项目可以直接使用：

opentrans.xyun.dev

当前项目线上官网地址为：

https://opentrans.xyun.dev/

如果未绑定自定义域名，工作流会自动根据仓库名计算 GitHub Pages 基础路径，默认可以部署到：

https://xy200303.github.io/OpenTrans/

GitHub 里具体去哪里配

如果你是第一次配仓库发布，建议按这个顺序点：

1. 打开仓库 Settings -> Pages，把 Source 切到 GitHub Actions
2. 打开 Settings -> Secrets and variables -> Actions -> Variables
3. 按需新增 DOCS_BASE
4. 如果要让工作流顺手写入域名，再新增 PAGES_CUSTOM_DOMAIN
5. 确认仓库里存在 website/public/CNAME

当前项目已经提交了：

website/public/CNAME = opentrans.xyun.dev

所以只要你的 DNS 已经把域名指到 GitHub Pages，一般不需要再改 VitePress 配置。

访问异常怎么排查

如果部署成功但访问还有问题，优先看这几项：

1. 页面能打开但样式或 JS 404 这通常是基础路径不对。自定义域名场景要确保 DOCS_BASE=/，或者仓库里已经有 website/public/CNAME。
2. 域名打不开 先确认 DNS 是否已经把 opentrans.xyun.dev 指向 GitHub Pages，对应记录通常需要指到 xy200303.github.io。
3. GitHub Actions 成功了但线上还是旧内容 GitHub Pages 有缓存和生效延迟，先等几分钟，再手动重新运行 docs 工作流。
4. 自定义域名恢复成了 github.io 地址 回到 Settings -> Pages 看 Custom domain 是否还在，必要时重新保存一次。

Docker Hub 自动发布

发布前需要配置以下 GitHub Secrets：

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

可选 GitHub Repository Variable：

• DOCKERHUB_REPOSITORY

如果未设置 DOCKERHUB_REPOSITORY，工作流默认推送到：

docker.io/<DOCKERHUB_USERNAME>/opentrans

DOCKERHUB_USERNAME 在哪里

DOCKERHUB_USERNAME 不是邮箱，也不是仓库名，它就是你的 Docker Hub 登录用户名。

你可以在这几个地方看到它：

• Docker Hub 右上角头像菜单里的账号名
• 个人主页 URL：https://hub.docker.com/u/<你的用户名>
• 镜像仓库 URL：https://hub.docker.com/r/<你的用户名>/opentrans

例如你的个人主页是：

https://hub.docker.com/u/xy200303

那 DOCKERHUB_USERNAME 就应该填：

xy200303

DOCKERHUB_TOKEN 在哪里拿

不要直接用密码，建议用 Docker Hub Personal Access Token：

1. 打开 Docker Hub
2. 进入 Account Settings
3. 打开 Personal access tokens
4. 新建一个给 GitHub Actions 用的 token
5. 把它保存到 GitHub Secret DOCKERHUB_TOKEN

GitHub 里具体去哪里配 Docker 发布

1. 打开仓库 Settings -> Secrets and variables -> Actions
2. 在 Secrets 里新增： DOCKERHUB_USERNAMEDOCKERHUB_TOKEN
3. 在 Variables 里按需新增： DOCKERHUB_REPOSITORY

如果你不填 DOCKERHUB_REPOSITORY，工作流会默认推到：

<DOCKERHUB_USERNAME>/opentrans

如果你想显式指定，也可以填成：

xy200303/opentrans

镜像标签策略

• push 到默认分支时发布 latest
• push v* 标签时发布版本标签，例如 v1.2.3
• 同时生成 sha-<commit> 便于回滚与排查

推荐发布方式

如果你想做正式版本发布，建议：

1. 先在本地确认 go test ./... 和 cd website && npm run build 都通过
2. 合并到 main 后自动发布 latest
3. 打 vX.Y.Z 标签后发布正式版本镜像

示例：

git tag v0.1.0
git push origin v0.1.0

其中官网构建命令是在 website/ 目录中执行：

cd website
npm install
npm run build

服务镜像本地验证命令为：

docker build -f services/opentransd/Dockerfile -t opentrans:local .

首次配置清单

如果你要从零把这套发布跑起来，最少做这几件事：

1. Settings -> Pages 里启用 GitHub Actions
2. Actions -> Variables 里确认 DOCS_BASE / PAGES_CUSTOM_DOMAIN
3. Actions -> Secrets 里填好 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN
4. 本地先跑 go test ./...
5. 本地再跑 cd website && npm run build
6. 如需验证服务镜像，再跑 docker build -f services/opentransd/Dockerfile -t opentrans:local .