Gogs Next 镜像实战：非 root、最小化与安全加固的 Docker 部署指南

Gogs 下一代（next）Docker 镜像是该项目面向生产环境的官方分发形式：自 0.16.0 起，它将成为默认镜像标签 gogs/gogs:latest，取代遗留的 legacy 镜像。本篇基于 docker-next/README.md 与配套构建文件展开，覆盖安全设计、app.ini 配置、内置 SSH 服务器、三种数据卷方案与首次启动、升级流程，并结合 Dockerfile.next 与 internal/conf 源码解释关键机制的底层实现，帮助你在 Docker 与 Kubernetes 环境中完成一次可落地、可审计的私有 Git 服务部署。

一、next 镜像定位：从 legacy 到安全优先

仓库中同时存在两套镜像体系：

• Dockerfile + docker/README.md：遗留镜像。官方文档明确标注其"缺乏现代安全最佳实践"，自 0.16.0 起以 gogs/gogs:legacy-latest 发布，且不晚于 0.17.0 完全移除。其 docker/ 目录内还有 s6 进程监督、crond、备份脚本等组件（见 docker/s6/、docker/runtime/）。
• Dockerfile.next + docker-next/README.md：下一代镜像，标签为 gogs/gogs:next-latest，是本文主角。

next 镜像的安全优先设计有四点：

1. 默认非 root 运行——使用 UID 1000 / GID 1000；
2. 最小镜像——只安装必需软件包；
3. 直接执行——没有进程监督器（supervisor），容器直接运行 gogs web；
4. 支持严格的安全上下文——可直接用于 Kubernetes。

源码级印证：Dockerfile.next 构建了什么

从 Dockerfile.next 的源码可以看到文档中各声明的具体实现：

FROM alpine:3.23

# Create git user and group with fixed UID/GID at build time ...
ARG GOGS_UID=1000
ARG GOGS_GID=1000
RUN addgroup -g ${GOGS_GID} -S git && \
    adduser -u ${GOGS_UID} -G git -H -D -g 'Gogs Git User' -h /data/git -s /bin/sh git

RUN apk --no-cache --no-progress add \
  bash ca-certificates curl git linux-pam openssh-keygen "zlib>1.3.2"

ENV GOGS_CUSTOM=/data/gogs
...
VOLUME ["/data", "/backup"]
EXPOSE 22 3000
HEALTHCHECK CMD (curl --noproxy localhost -o /dev/null -sS http://localhost:3000/healthcheck) || exit 1

USER git:git
ENTRYPOINT ["/app/gogs/start.sh"]
CMD ["/app/gogs/gogs", "web"]

要点与文档的对应关系：

• ARG GOGS_UID=1000 / ARG GOGS_GID=1000 解释了为什么构建期 UID/GID 可定制（见下文"构建期自定义 UID/GID"）；注释也说明了选 1000 的原因——它是与多数卷权限方案兼容的通用非 root 值。
• 运行时仅安装 bash、ca-certificates、curl、git、linux-pam、openssh-keygen 等少量包，印证"最小镜像"；其中 curl 正是供 HEALTHCHECK 使用。
• ENV GOGS_CUSTOM=/data/gogs 是"自定义目录"机制的入口，源码依据见下文配置一节。
• 镜像直接以 USER git:git + CMD ["/app/gogs/gogs", "web"] 运行，没有任何 supervisor，对应文档中"Direct execution"的设计。
• 入口脚本 docker-next/start.sh 极短：启动时执行 mkdir -p /data/gogs /data/git（注释说明：当 /data 是挂载卷时目录尚不存在），随后 exec "$@" 直接替换为 gogs web 进程，保证容器 PID 1 就是 Gogs 主进程，信号能直接传递。

Kubernetes 安全上下文示例

在 Deployment YAML 中确保存在以下片段（摘自原文档）：

spec:
  template:
    spec:
      securityContext:
        fsGroup: 1000
        fsGroupChangePolicy: OnRootMismatch
      containers:
      - name: gogs
        securityContext:
          runAsNonRoot: true
          runAsUser: 1000
          runAsGroup: 1000
          allowPrivilegeEscalation: false
          seccompProfile:
            type: RuntimeDefault
          capabilities:
            drop:
              - ALL

fsGroup: 1000 与镜像内 git 用户 GID 保持一致，OnRootMismatch 保证已有卷不会每次挂载都被重写属主；容器级 runAsNonRoot + drop: ALL 与镜像"非 root + 最小化"的设计是配套的——如果镜像本身以 root 启动，这些约束根本无法满足。

构建期自定义 UID/GID

如果宿主环境对 1000 有冲突（例如该 UID 已被其他服务占用），可用构建参数换一套：

docker build -f Dockerfile.next --build-arg GOGS_UID=1001 --build-arg GOGS_GID=1001 -t my-gogs .

由于 UID/GID 是在 adduser/addgroup 时固定写入镜像的，必须重新构建而非运行时修改。同时请同步调整：宿主机目录的 chown、Kubernetes 的 runAsUser/fsGroup，以及 app.ini 中 RUN_USER = git（用户名不变，只是 UID 变了，详见下文 RUN_USER 校验机制）。

二、配置：app.ini 覆盖式加载与 ${...} 环境变量展开

为什么镜像要求"先有 app.ini 才能启动"

Gogs 的自定义配置目录由环境变量 GOGS_CUSTOM 决定。从源码 internal/conf/computed.go 看：

// CustomDir returns the absolute path of the custom directory that contains local overrides.
// It reads the value of environment variable GOGS_CUSTOM. When not set, it uses the work
// directory returned by WorkDir function.
func CustomDir() string {
	customDirOnce.Do(func() {
		customDir = os.Getenv("GOGS_CUSTOM")
		if customDir != "" {
			return
		}
		customDir = filepath.Join(WorkDir(), "custom")
	})
	return customDir
}

next 镜像在 Dockerfile.next 中显式设置了 ENV GOGS_CUSTOM=/data/gogs，因此容器内 /data/gogs 本身就是"自定义目录"——/data/gogs/conf/app.ini 会被加载并与镜像内置默认值（conf/app.ini）做覆盖合并。文档原文对此有明确提示：app.ini 是叠加在出厂默认值之上的，只写你真正要改的键即可，不需要复制整份默认配置。

完整配置示例（原样继承自文档）

以这样的场景为例：Gogs 对外提供 https://gogs.example.com，容器 HTTP 端口 3000 映射到宿主机 10880，SSH 端口映射到 10022，数据库使用宿主机上的 PostgreSQL：

RUN_MODE = prod
; USE AS-IS because the image already created this user with UID 1000.
RUN_USER = git

[server]
EXTERNAL_URL = https://gogs.example.com/
DOMAIN       = gogs.example.com

[repository]
; USE AS-IS to match the data volume layout shipped in the image.
ROOT = /data/git/gogs-repositories

[database]
TYPE     = postgres
; Use host.docker.internal (or the host's LAN IP) to reach a DB on the host.
HOST     = host.docker.internal:5432
NAME     = gogs
USER     = gogs
PASSWORD = ${GOGS_DATABASE_PASSWORD}

[security]
SECRET_KEY = ${GOGS_SECURITY_SECRET_KEY}

各关键项说明：

键	作用	备注
RUN_MODE	运行模式（dev/prod/test），见 conf/app.ini 第 10-11 行	生产环境设为 prod
RUN_USER	应运行 Gogs 的系统用户	镜像内已创建 git 用户（UID 1000），保持 git 不变
EXTERNAL_URL	对外访问地址，生成 clone URL、回调地址的基础	必须与前端可达地址一致
DOMAIN	对外域名	与 EXTERNAL_URL 的 host 一致
repository.ROOT	仓库根目录	固定为 /data/git/gogs-repositories，与镜像数据卷布局匹配（源码默认值见 internal/conf/conf.go，HomeDir() 下拼接 gogs-repositories，而容器内 HOME=/data/git）
database.*	数据库连接	HOST 用 host.docker.internal 访问宿主机上的数据库
security.SECRET_KEY	会话与签名密钥	见下方"SECRET_KEY 强制校验"

RUN_USER 的强校验：这不是普通配置——internal/conf/conf.go 在初始化时调用 CheckRunUser，如果配置的用户名与进程实际运行的用户不匹配，Gogs 直接报错退出。这就是为什么文档强调"USE AS-IS"：镜像已经创建了 git 用户，你只需保持一致。

SECRET_KEY 强制校验：文档说"Gogs 会在仍使用不安全默认值时拒绝启动"，源码依据是 internal/conf/conf.go：

if Security.SecretKey == "" || Security.SecretKey == "CHANGE-ME-OR-FAIL-TO-START" {
	return errors.New("[security] SECRET_KEY must be set to a strong, unguessable value")
}

SECRET_KEY 可以是任意不可猜测的字符串（例如 UUID）。

${...} 环境变量展开：密钥不落盘

文档特别注明：任何配置值中的 ${...} 引用会在启动时从容器环境变量展开，这样密钥就不必写进磁盘上的 app.ini。源码中对应实现只有一行，见 internal/conf/conf.go：

File.ValueMapper = os.ExpandEnv

即 ini 解析器对每个值调用 os.ExpandEnv。因此：

docker run -e GOGS_DATABASE_PASSWORD=… -e GOGS_SECURITY_SECRET_KEY=… gogs/gogs:next-latest
# 或使用 --env-file secrets.env

纯字面值同样可行（例如 PASSWORD = hunter2），但推荐用环境变量把敏感项留在进程环境里。

关于更多配置键的细节，可参考仓库内的 配置入门文档。

三、Git over SSH：启用内置 SSH 服务器

next 镜像内置 SSH 服务器（这是与 legacy 镜像的关键差异之一：legacy 镜像不支持内置 SSH 服务器，见 docker/README.md 示例中 START_SSH_SERVER = false 的注释）。

重要：启用或禁用内置 SSH 服务器需要重启容器才能生效。

在 app.ini 中配置：

[server]
START_SSH_SERVER = true
; The port exposed by `docker run -p 10022:2222`. Shown in clone URLs.
SSH_PORT         = 10022
; The port that the builtin SSH server listens on.
SSH_LISTEN_PORT  = 2222

两个端口的分工是理解这段配置的核心：

• SSH_LISTEN_PORT = 2222：容器内 Gogs 内置 SSH 服务器实际监听的端口（镜像默认出厂值是 22，见 conf/app.ini 中 SSH_PORT = 22，内置模式下默认 SSH_LISTEN_PORT = %(SSH_PORT)s 即同端口）。
• SSH_PORT = 10022：对外部用户暴露的端口，会写进 Gogs 生成的 clone URL（例如 git@host:10022/user/repo.git），对应 docker run -p 10022:2222 的端口映射。

把容器端口设为 2222 而不是 22，正是非 root 运行的必然结果：非特权进程无法绑定 1024 以下的端口，这也再次呼应了"直接执行、无特权"的设计。START_SSH_SERVER 出厂默认是 false（见 conf/app.ini 第 77 行），即默认只走 HTTP/HTTPS，需要 Git over SSH 时显式打开。

四、数据卷：/data 布局与三种落地方式

容器内目录布局

文档给出的 /data 目录结构：

/data
|-- git
|   |-- gogs-repositories
|-- ssh
|   |-- # ssh public/private keys for Gogs
|-- gogs
    |-- conf
    |-- data
    |-- log

对应关系：repository.ROOT 指向 /data/git/gogs-repositories；内置 SSH 主机的公钥/私钥放在 /data/ssh；GOGS_CUSTOM=/data/gogs 下则放着 conf（你的 app.ini）、data、log。

Dockerfile 声明的卷是 VOLUME ["/data", "/backup"]：/backup 用于镜像自带的备份机制（legacy 镜像的定时备份组件见 docker/runtime/backup-*.sh），next 镜像把数据与备份统一收到这两个卷。

方式一：Bind mount（绑定挂载）

把 app.ini 写在宿主机目录，再用 -v 挂入容器。注意 chown 必须在挂载前完成，因为容器以 UID 1000 运行，读不到 root 属主的文件：

$ mkdir -p /var/gogs/gogs/conf
$ chown -R 1000:1000 /var/gogs
$ vi /var/gogs/gogs/conf/app.ini   # 粘贴上面的示例并修改
$ docker run --name=gogs -p 10022:2222 -p 10880:3000 -v /var/gogs:/data gogs/gogs:next-latest

方式二：Named volume（命名卷）

命名卷位于 Docker 存储内部，文件必须借容器之手写入。由于 Gogs 没有 app.ini 拒绝启动，容器必须先 create（而不是 run）：

$ docker volume create --name gogs-data
$ docker create --name=gogs -p 10022:2222 -p 10880:3000 -v gogs-data:/data gogs/gogs:next-latest
$ docker cp app.ini gogs:/data/gogs/conf/app.ini
$ docker run --rm -v gogs-data:/data alpine chown -R 1000:1000 /data/gogs/conf
$ docker start gogs

其中 chown 步骤的原因值得单独说明：非 root 镜像以 UID 1000 运行，而 docker cp 写入的文件属主是 root，不修正属主 Gogs 将无法读取自己的配置。

方式三：自定义目录

文档特别澄清了一个 Docker 用户常见误区："custom 目录"在容器内并不神秘——/data/gogs 本身就是 custom 目录（由 GOGS_CUSTOM 环境变量指定，机制见上文源码分析），不需要再建一层嵌套，直接在那里编辑文件即可。

端口映射小结

容器端口	宿主机端口（示例）	用途
3000	10880	Web/HTTP（HTTP_PORT 出厂默认 3000）
2222	10022	内置 Git SSH（SSH_LISTEN_PORT → SSH_PORT）

五、首次启动：注册管理员或 CLI 创建

Gogs 要求 app.ini 就绪后才能启动，且 SECRET_KEY 必须有效，启动后就有两条路径创建管理员：

路径一（Web 注册）：打开 https://gogs.example.com/ 注册账号。规则是：在尚无任何用户时，第一个注册的人自动成为管理员。

路径二（CLI）：在宿主机上执行，命令在容器内运行，因此通过同一份 app.ini 访问数据库，不存在"配置不一致"问题：

$ docker exec -it gogs gogs admin create-user \
    --name admin \
    --password ${PASSWORD} \
    --email [e-mail] \
    --admin \
    --config /data/gogs/conf/app.ini

--config /data/gogs/conf/app.ini 显式指向容器内 custom 目录下的配置文件。Gogs 启动后，日常运维使用 docker start gogs / docker stop gogs 即可。

健康检查

Dockerfile.next 声明了健康检查：

HEALTHCHECK CMD (curl --noproxy localhost -o /dev/null -sS http://localhost:3000/healthcheck) || exit 1

被探测的端点在 cmd/gogs/internal/web/web.go 中注册：

m.Route("/healthcheck", http.MethodHead+","+http.MethodGet, healthCheck)

即 Web 服务同时支持 HEAD 与 GET /healthcheck，Docker 据此判断容器状态（docker ps 的 health 列、编排系统重启策略都以它为准）。

六、升级流程

警告：升级前务必确认数据已经卷挂到容器之外！

以 Docker 方式升级 Gogs 的步骤（完整继承自文档）：

1. docker pull gogs/gogs:next-latest —— 拉取新版镜像；
2. docker stop gogs —— 停止旧容器；
3. docker rm gogs —— 删除旧容器（数据在卷里，不受影响）；
4. 像首次启动那样重建容器，不要遗漏与首次相同的卷挂载和端口映射。

这里删除的是"容器"而非"数据"：/data（以及 /backup）挂在卷上，app.ini、仓库、日志全部保留，新容器重建后读到的仍是同一份数据与配置。

七、总结

next 镜像把"非 root、最小化、无监督器、可上 K8s"落到了每一层：Dockerfile.next 用构建参数固定 1000:1000 用户与少量运行包，start.sh 只做建目录和 exec 透传，GOGS_CUSTOM=/data/gogs 让 custom 目录即数据卷，而 RUN_USER 匹配、SECRET_KEY 强校验、os.ExpandEnv 密钥展开这些启动期强制检查（均在 internal/conf 中实现）则保证了安全配置不是"建议"而是"不满足就起不来"。按本文顺序完成配置（含 ${...} 环境变量）、卷挂载（bind mount 或命名卷 + chown 1000:1000）、SSH 端口配置后，即可获得一个在 docker ps 健康检查与 Kubernetes 严格 securityContext 下都站得住的 Gogs 实例；后续升级只需按 pull → stop → rm → 重建容器四步走。