CI: build and publish the container image to GHCR

The Dockerfile's builder stage already runs the unit suite, so the workflow
deliberately has no separate test job -- a red test cannot produce an image.

After pushing, the published artifact is smoke-tested by digest: `--version`
covers a runtime stage missing a shared library, and `--check` against a
throwaway credentials file covers the config baked into the image. Both were
failure modes a green build would not have caught. The `--check` invocation is
verified locally against docker/openvpngate.conf.

`latest` follows the newest v* tag rather than the branch head; master head is
published as `master`. Registry paths are lowercased explicitly rather than
relying on metadata-action, since the same value is reused for the smoke test.

GHCR_TOKEN / GHCR_USER / GHCR_IMAGE override the built-ins so this still works
from a mirror or a Gitea/Forgejo runner, where the ambient token authenticates
to the wrong registry. On github.com none of them need to be set.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/DOCKER.md

@@ -38,6 +38,8 @@ curl -x socks5h://alice:口令@127.0.0.1:1080 https://ifconfig.me
 `socks5h` 让 curl 把域名交给代理去解析（DNS 走隧道，不泄漏）；`socks5` 是本地解析后只把
 IP 交过来。两条路径都支持，但只有前者是你部署 VPN 网关想要的那条。
 
+不想在本机编译 openvpn3 的话，[§9](#9-ci-与-ghcr-发布) 说了怎么改成拉现成镜像。
+
 ---
 
 ## 2. 镜像里有什么
@@ -212,7 +214,11 @@ uid 写死成 10001 而不是让发行版随便分配，就是为了这条命令
   `sha256$salt$hash`，起 direct 模式代理，正确口令拿到 200，错误口令和不存在的用户都被
   `auth rejected` 挡下；
 - 管理路由清单来自 `src/app/admin_server.cpp`；
-- `docker-compose.yml` 的 YAML 结构解析通过（挂载目标、profiles、tmpfs、healthcheck 覆盖）。
+- **`docker/openvpngate.conf` 本身是实测能解析的**：拿它配一个临时凭据文件跑
+  `openvpngate -c docker/openvpngate.conf --check`，输出 `config ok` 且
+  `socks5 0.0.0.0:1080 auth=required users=1`——即 §3 那三处覆盖确实生效了。CI 里对镜像跑的
+  就是同一条命令；
+- `docker-compose.yml` 与 `.github/workflows/publish-image.yml` 的 YAML 结构解析通过。
 
 **没有验证**
 
@@ -222,6 +228,8 @@ uid 写死成 10001 而不是让发行版随便分配，就是为了这条命令
 - `create_host_path: false` 的报错行为；
 - 容器里 `CapEff` 是否真是全零（按 Docker 语义应当如此，但没实跑）。
 
+上面前两条会在 CI 第一次跑通时自动补上（§9 的 smoke 步骤），剩下三条只能在真机上验。
+
 接手后按顺序跑一遍就能补齐：
 
 ```sh
@@ -235,3 +243,56 @@ docker compose stop                        # 应在一秒内退出，不是等
 
 最后一条尤其值得看：本项目已经被「优雅退出日志打得漂漂亮亮然后永远不退出」这类 bug 咬过
 一次（README §5 末尾那段），`docker stop` 卡满宽限期然后被 SIGKILL，就是它在容器里的样子。
+
+---
+
+## 9. CI 与 GHCR 发布
+
+`.github/workflows/publish-image.yml` 构建镜像并推到 GitHub Container Registry。
+
+**它没有单独的测试 job，这是故意的**：Dockerfile 的构建阶段最后一步就是跑完整单元测试
+（`OVG_RUN_TESTS=1`），测试挂了镜像就构建不出来，也就发布不了。再加一个跑同一套测试的 job
+只是把同样的编译做第二遍。
+
+推完之后还有一步 smoke：按 **digest**（不是 tag）把刚发布的那个镜像拉回来，跑
+`--version`，再挂一个临时凭据文件跑 `--check`。这两下覆盖的正是「构建绿了也不代表能跑」的
+两件事——运行时阶段有没有漏装共享库，以及镜像里烤进去的那份配置能不能解析。
+
+产出的 tag：
+
+| 触发 | tag |
+|---|---|
+| push 到 `master` | `master`、`sha-<短 hash>` |
+| push tag `v1.2.3` | `1.2.3`、`1.2`、`latest`、`sha-<短 hash>` |
+| pull request | 照常构建并跑测试，**不推** |
+
+`latest` 跟的是最新的 release tag，不是分支头。在打出第一个 `v*` 之前，要拉的是 `master`。
+
+拉现成镜像而不是本地编译，把 `docker-compose.yml` 里的 `build:` 整块删掉，`image:` 改成：
+
+```yaml
+    image: ghcr.io/<owner>/<repo>:master
+```
+
+`docker compose pull && docker compose up -d` 即可。注意 `docker/openvpngate.conf` 和
+`docker/socks5.auth` 仍然要从本仓库挂进去（§3），镜像里那份只是兜底默认值。
+
+### 这个仓库的 remote 不是 GitHub
+
+`origin` 指向 `git.sfclub.cc`。`.github/workflows/` 只有在下面两种情况下会跑：
+
+1. **镜像到 github.com**：什么都不用配。内置的 `GITHUB_TOKEN` 配合 workflow 里的
+   `permissions: packages: write` 就能推 ghcr.io，包会挂在镜像仓库名下。
+2. **在 Gitea/Forgejo Actions 上跑**：它们认这个 workflow 语法，但它们发的 `GITHUB_TOKEN`
+   认证的是**自己那个 registry**，推不了 ghcr.io。需要在仓库里配：
+
+   | 名字 | 类型 | 值 |
+   |---|---|---|
+   | `GHCR_TOKEN` | secret | GitHub PAT，勾 `write:packages` |
+   | `GHCR_USER` | variable | 那个 PAT 对应的 GitHub 用户名 |
+   | `GHCR_IMAGE` | variable | 目标镜像名，如 `icybear/openvpngate`。这里的仓库名和 GitHub 上想要的名字不一定一样 |
+
+   三个都是「有就用、没有就退回内置值」，所以在 github.com 上不配也不会碍事。
+
+首次推送后包默认是私有的。要让别人 `docker pull` 得先在 GitHub 的 Package settings 里改成
+public，或者让对方 `docker login ghcr.io`。