Gogs 0.15 版本变更全解读：安全加固、安装流程重构与配置迁移实战指南

Gogs 是一个用 Go 编写、追求“无痛自托管”的轻量级 Git 服务（本仓库即其 main 分支源码，对应 CHANGELOG 中的 0.15.0+dev）。本文以仓库根目录的 CHANGELOG.md 为骨架，系统梳理自 0.12 以来历次发布的功能演进、安全修复与破坏性变更，并结合 conf/app.ini 与 internal/、cmd/gogs/ 下的源码实现，给出可直接落地的升级与配置迁移清单。读完你将掌握：0.15 与 0.14 各版本改了什么、哪些配置项被移除或更名、如何把旧实例安全升级到当前基线，以及各类安全修复对应的防护机制。

一、为什么这篇变更日志值得逐条细读

CHANGELOG 通常只是“发布流水账”，但 Gogs 的这份日志浓缩了三个高价值信息维度：

1. 安全公告密度极高：0.14.x 的每个补丁版本都包含大量 GHSA（GitHub Security Advisory）编号的安全修复，从 SSRF、RCE 到存储型 XSS 与认证绕过，属于自托管服务最需要关注的“高危动作片”。
2. 配置模型连续演进：0.13 一次性移除十余个旧配置项，0.15 又移除了 /install 页面与 INSTALL_LOCK，配置迁移是升级的主要工作量所在。
3. 工程架构换代：数据库后端收窄（移除 MSSQL）、缓存适配器收窄（移除 memcache）、Docker 镜像发行策略重做、构建链从 Makefile/CGO 迁移到 Task + 纯 Go SQLite。

本仓库根目录的 conf/app.ini 文件头注释即写明“NEVER EVER MODIFY THIS FILE”，所有改动都应落到 custom/conf/app.ini——这一约定与 0.15“必须自备可用配置文件”的新安装流程直接呼应。

二、0.15.0+dev：主分支正在发生的破坏性重构

0.15 是一个“瘦身 + 收紧”的大版本，围绕四件事展开。

2.1 安装流程重构：/install 页面与 INSTALL_LOCK 退出历史

CHANGELOG 明确记录，Web 端首次安装页 /install 与配置项 [security] INSTALL_LOCK 已被移除（对应 PR #8350）。新实例必须自带一份可用的 custom/conf/app.ini 才能启动，不再存在“先启动再网页配置”的引导路径。

同时“使用 Go 模板文件自定义页面”的能力被停止支持。这与当前仓库的 templates/（以 .tmpl 为准）与 public/（含 embed.go）目录结构相符——资源默认以嵌入式 bindata 打进二进制（LOAD_ASSETS_FROM_DISK 默认 false，见 conf/app.ini）。

实操要点：

• 部署前先对照 conf/app.ini 复制一份到 custom/conf/app.ini 并填写 [server]、[database]、[security] 等必需段；
• [security] SECRET_KEY 默认为占位符 CHANGE-ME-OR-FAIL-TO-START，文件注释直言“不改它服务将拒绝启动”，务必改成随机强密钥；
• 备份与恢复通过 cmd/gogs/backup.go、cmd/gogs/restore.go 的子命令完成（Docker 场景可参考 docker/runtime/backup-job.sh 与 docker/runtime/backup-rotator.sh 的保留策略脚本）。

2.2 安全基线收紧：自我注册默认关闭

[auth] DISABLE_REGISTRATION 的默认值被改为 true。也就是说，新实例默认不允许用户自助注册，账户只能由管理员创建；如确需开放注册，必须在配置中显式写回：

[auth]
DISABLE_REGISTRATION = false

该默认值已同步体现在本仓库 conf/app.ini（[auth] 段中 DISABLE_REGISTRATION = true），且配置结构的定义位于 internal/conf/static.go（AuthOpts 结构体）。同段其余默认值一并列出，便于核对：

配置项（位于 [auth]）	当前默认	说明
DISABLE_REGISTRATION	true	关闭自助注册（0.15 起默认收紧）
REQUIRE_EMAIL_CONFIRMATION	false	新邮箱需邮件确认
ENABLE_REGISTRATION_CAPTCHA	true	注册页验证码
ACTIVATE_CODE_LIVES	180	激活码有效期（分钟）
RESET_PASSWORD_CODE_LIVES	180	重置密码码有效期（分钟）
REVERSE_PROXY_AUTHENTICATION_HEADER	X-WEBAUTH-USER	反向代理认证用户名头
TRUSTED_PROXY_IPS	127.0.0.0/8,::1/128	允许设置认证头的来源地址

2.3 大幅删减：MSSQL、memcache、gogs cert、CSRF、DSA、调试端点

0.15 的 Removed 清单是一份典型的“架构收窄”声明，逐项说明如下：

移除对象	影响与替代
/install 页面与 [security] INSTALL_LOCK	必须自带可用 custom/conf/app.ini（PR #8350）
MSSQL 数据库后端（PR #8173）	仅支持 PostgreSQL / MySQL / SQLite3。源码依据：internal/database/database.go 中仅存在 postgres、mysql、sqlite3 三类分支；go.mod 中也只保留 lib/pq、go-sql-driver/mysql 与 SQLite 驱动
memcache 缓存适配器（PR #8270）	[cache] ADAPTER 仅剩 memory 与 redis
gogs cert 子命令（PR #8153）	证书生成改由外部工具完成（HTTPS 证书可参考 openssl pkcs12 转换，conf/app.ini [server] 段有指引）
[email] DISABLE_HELO（PR #8164）	SMTP 握手阶段始终发送 HELO/EHLO
/debug、/debug/pprof/*、/debug/profile/*、/urlmap.json（PR #8271）	移除调试与路由表暴露端点
CSRF 防护与 [session] CSRF_COOKIE_NAME（PR #8300）	安全模型改为“仅信任服务端下发会话 Cookie”
DSA 公钥支持（PR #8313）	[ssh.minimum_key_sizes] 下 DSA 项不再被识别

提示：0.15 移除 CSRF 中间件与“记住我”Cookie，都是同一安全思路的落地——不再使用可从数据库字段推导、可被伪造/携带的凭证，会话持久化统一收敛到服务端签发的会话 Cookie（其名称默认 i_like_gogs，见 conf/app.ini [session] 段）。

2.4 Docker 镜像发行策略重定位

0.15 起（PR #8278）：

• main 分支构建只发布为 gogs/gogs:edge，使用下一代 Dockerfile.next；
• 旧版 Dockerfile 不再产出 main 构建；
• gogs/gogs:latest 与 gogs/gogs:next-latest 永远指向最新已发布稳定版，绝不再指向旧分支上的补丁。

更早的 0.14.1（PR #8061）已经铺垫了这一策略：下一代安全加固镜像先以 gogs/gogs:next-latest 发布，自 0.16.0 起成为默认分发（即 latest），旧镜像自 0.16.0 起以 gogs/gogs:legacy-latest 发布，最迟 0.17.0 完全移除。仓库中同时保留 Dockerfile 与 Dockerfile.next 即是这一过渡期的实物证据。计划用 Docker 部署的团队，应尽早基于 Dockerfile.next 验证启动脚本（docker-next/start.sh）与 s6 进程编排（docker/s6/）。

2.5 0.15 修复的三组安全漏洞

• 开放重定向：/redirect 端点及各类 post-action 流程可借目标地址中的反斜杠绕过校验（PR #8391，GHSA-3g28-2vwg-gxq6）。
• 参数注入（信息泄露）：多个仓库 API 端点对精心构造的 commit/branch 引用处理不当，拥有只读权限的已认证用户可把内部服务器细节注入错误日志（PR #8393，GHSA-mxrh-2rxr-6mqc）。
• 参数注入（任意文件写入）：创建 Pull Request 时若分支名被恶意构造，拥有写权限的用户可在服务器任意路径写入文件（PR #8390，GHSA-2grc-qr7q-6m36）。

这几项与 0.14.3 的 RCE 修复（PR #8301，GHSA-qf6p-p7ww-cwr9：PR rebase 合并配合构造分支名实现远程命令执行）同属“把用户可控字符串拼进 git/SSH 命令参数”这一攻击面，印证 Gogs 把分支名、提交引用、标签名等都视为高危输入。

三、0.14.3：一次集中爆发的大规模安全修复

0.14.3 几乎是一份“安全专版”，按风险类别整理如下，便于运维团队判断升级优先级。

3.1 认证与会话（务必第一时间升级）

漏洞	修复后机制
反向代理认证头被任意来源信任，可伪装任意用户（GHSA-w6j9-vw59-27wv）	仅信任 [auth] TRUSTED_PROXY_IPS 所列地址发来的认证头。默认仅回环地址：127.0.0.0/8,::1/128（见 conf/app.ini），配置结构见 internal/conf/static.go（TrustedProxyIPs/TrustedProxyCIDRs）
附件下载端点缺少鉴权，知道 UUID 即可下载私有仓库附件（GHSA-p9f5-h3rx-j5qw）	对附件下载补齐授权校验
组织团队/成员管理操作接受 GET 请求，可诱导管理员将攻击者加入 Owners 团队（GHSA-pwx3-qcgw-vh7h）	改为仅接受安全方法
写级协作者可通过 API 修改仅限管理员的仓库设置（issue 跟踪器、wiki、镜像同步）（GHSA-268j-37xf-pp52）	补充管理员级鉴权
只读 Git HTTP 访问可能被当作写权限用于 push（GHSA-wmfg-5p4h-5fw3）	修正 HTTP 传输层读写判定
密码重置令牌沿用了账户激活有效期，忽略 [auth] RESET_PASSWORD_CODE_LIVES（GHSA-5c3f-6486-3g7g）	重置码严格遵循配置生命周期

3.2 SSRF 与网络访问控制

0.14.3 集中修补 webhook、镜像、迁移等“服务端主动发起网络请求”场景的 SSRF：

• webhook 投递跟随 HTTP 重定向时可访问内网地址（GHSA-c4v7-xg93-qf8g）；
• 镜像地址更新绕过 clone 地址校验（GHSA-wv27-2vqp-j7g5）；
• 迁移与周期镜像同步在 HTTP 重定向与存储镜像 URL 的过期 host 校验下被 SSRF（GHSA-g2f5-gjr4-qjvm）。

这条防线自 0.12.6 起逐步建立：新增 [security] LOCAL_NETWORK_ALLOWLIST（逗号分隔、可访问内网的主机名列表，见 conf/app.ini [security] 段），0.12.8 起对所有用户（含管理员）生效，0.12.10 起支持 * 通配全部主机名。因此没有在 LOCAL_NETWORK_ALLOWLIST 中显式放行的内网主机，无法被迁移/镜像/webhook 访问，这是对抗 SSRF 的默认安全姿势。

3.3 RCE / 命令注入 / 路径穿越

• PR rebase 合并 + 构造分支名 → 远程命令执行（GHSA-qf6p-p7ww-cwr9）；
• 上传文件名经过已提交目录符号链接时，可在仓库工作树之外任意写文件（GHSA-89mr-xqfv-758m）；
• API 接受的组织名存在路径穿越 → 远程代码执行（GHSA-c39w-43gm-34h5）。

历史上同类问题还包括：0.13.x 中 Git hook 编辑的路径穿越读写（GHSA-mrph-w4hh-gx3g）、文件编辑 UI 的路径穿越（GHSA-wj44-9vcg-wjq7 / GHSA-r7j8-5h9c-f6fx / GHSA-qf5v-rp47-55gg）、文件上传/编辑的命令注入与 RCE（GHSA-xh32-cx6c-cp4v 等）。可见“文件名/分支名/组织名 → 文件系统路径 → 命令参数”是 Gogs 反复加固的重灾区，升级到最新版是第一要务。

3.4 存储型 XSS 与渲染层防护

0.14.3 密集修复了 Jupyter notebook（.ipynb）预览中的多条 XSS 链：javascript: URL、绕过 sanitizer 的 data:text/html URI、Markdown 单元格原始 HTML（GHSA-jq8v-rmf6-65jw / GHSA-3w28-36p9-w929 / GHSA-6vxv-wg6j-5qwp）。同期还有里程碑下拉框的构造名称存储型 XSS（GHSA-vcm5-gvmp-78mp）。这类修复位于仓库的 internal/markup/ 渲染与净化链路（sanitizer.go），并在 public/plugins/ 中随 notebookjs、DOMPurify、marked 等前端库升级而加固。

3.5 DoS、LFS 与 SSH

• 畸形外部 issue 跟踪器 URL 触发引用渲染时造成拒绝服务（GHSA-4j89-2c4f-44c6）；
• 把已知 OID 绑定到另一仓库（无需证明持有字节）可跨仓库泄露 LFS 对象内容（GHSA-6p9m-q3jp-47h4）；
• 停滞的 SSH 握手会无限期占用文件描述符与 goroutine，内置 SSH 服务器现强制 15 秒未完成握手即断开（GHSA-xp79-5mx3-jx52）。

SSH 握手超时机制的实现位于 internal/ssh/ssh.go：对传入连接先设置 SetDeadline(now + 15s) 约束握手阶段，握手成功后清除该截止时间——这既是修复证据，也提示自托管用户：内置 SSH 服务器（[server] START_SSH_SERVER）对慢速/恶意连接已有资源保护。

四、0.14.2 与 0.14.1：API 收口、会话与构建现代化

4.1 0.14.2：Access Token 仅允许 Header 传递

自 0.14.2 起，通过 URL 查询参数（token、access_token）传 API 令牌的方式被移除（PR #8177，GHSA-x9p5-w45c-7ffc），必须改用 Authorization 请求头。这不仅防令牌在日志/Referrer 中泄露，也便于 CDN/网关统一控制。所有依赖旧式查询参数调 API 的脚本都必须改造：

Authorization: token <your-access-token>

0.14.2 还修复了：仓库/wiki 文件列表页被构造文件名触发的 DoS（GHSA-3qq3-668m-v9mj）、LFS 跨仓库对象覆写（缺少内容哈希校验，GHSA-gmf8-978x-2fg2）、issue 评论 data URI 存储型 XSS（GHSA-xrcr-gmf5-2r8j）、release 删除中的标签选项注入（GHSA-v9vm-r24h-6rqm）、分支与 wiki 视图在作者/提交者名上的存储型 XSS（GHSA-vgvf-m4fw-938j）、issue 页 DOM XSS（GHSA-vgjm-2cpf-4g7c），以及 Web 编辑器与 API 无法更新文件的回归（PR #8184）。

4.2 0.14.1：面向 0.16 的技术铺垫

功能与工程层面的主要变化：

• 配置支持环境变量展开：app.ini 中值可写成 ${DATABASE_PASSWORD} 形式（PR #8057），机密不再硬编码进文件——适合容器化与密钥管理服务注入；
• Redis 会话支持 TLS：[session] PROVIDER_CONFIG = ...,tls=true（PR #7860），完整参数形态见 conf/app.ini [session] 段注释（network=tcp,addr=:6379,password=...,db=0,pool_size=100,idle_timeout=180）；
• 自定义登出跳转：[auth] CUSTOM_LOGOUT_URL（PR #8089），用于退出登录后跳转门户/SSO 登出页；
• 纯 Go SQLite 驱动：不再需要 CGO 即可编译（PR #7882），go.mod 中 modernc.org/sqlite 与 mattn/go-sqlite3 并存即是过渡期证据；注意同一版本将源码编译所需 Go 版本提升到 1.25；
• 新增比较标签与分支、文件浏览时标签页标题显示文件名、Mermaid 升级到 11.9.0（对应 public/plugins/mermaid-11.12.1/）；
• 仓库根目录已存在时中止创建并保持目录不动（PR #8091），避免初始化冲突（行为与 internal/database/ 的仓库/组织目录初始化逻辑配套）；
• 内置 SSH 密码算法可配置：[server] SSH_SERVER_MACS（如 [e-mail], hmac-sha2-256, hmac-sha1）与 SSH_SERVER_ALGORITHMS（如 rsa, ecdsa, ed25519）在此前的 0.13.0 加入，默认值均已落在 conf/app.ini [server] 段。

0.13.x 的其他实用入口也应知晓：个人访问令牌可用在密码字段完成 HTTP 认证、仓库支持“不列出”（unlisted）可见性、Markdown 支持 Mermaid 渲染、新增 PUT /repos/:owner/:repo/contents/:path 内容创建/更新 API、新增 [git.timeout] DIFF 超时与 [repository] DEFAULT_BRANCH 等配置（均见 0.13.0 的 Added 清单，其中 conf/app.ini 的 [repository] DEFAULT_BRANCH = master 为当前仓库默认值）。

五、0.13.0 配置大迁移对照表（升级必查）

0.13.0 一次性将一批“历史命名”的配置段/项标记移除。请对照下表逐项迁移（左侧全部不再生效，必须改用右侧）：

旧配置（已失效）	新配置
[mailer]	[email]
[service]	[auth]
APP_NAME	BRAND_NAME
[security] REVERSE_PROXY_AUTHENTICATION_USER	[auth] REVERSE_PROXY_AUTHENTICATION_HEADER
[auth] ACTIVE_CODE_LIVE_MINUTES	[auth] ACTIVATE_CODE_LIVES
[auth] RESET_PASSWD_CODE_LIVE_MINUTES	[auth] RESET_PASSWORD_CODE_LIVES
[auth] ENABLE_CAPTCHA	[auth] ENABLE_REGISTRATION_CAPTCHA
[auth] ENABLE_NOTIFY_MAIL	[user] ENABLE_EMAIL_NOTIFICATION
[auth] REGISTER_EMAIL_CONFIRM	[auth] REQUIRE_EMAIL_CONFIRMATION
[session] GC_INTERVAL_TIME	[session] GC_INTERVAL
[session] SESSION_LIFE_TIME	[session] MAX_LIFE_TIME
[server] ROOT_URL	[server] EXTERNAL_URL
[server] LANDING_PAGE	[server] LANDING_URL
[database] DB_TYPE	[database] TYPE
[database] PASSWD	[database] PASSWORD

同样在 0.13.0 移除的还有 [other] SHOW_FOOTER_VERSION、[server] STATIC_ROOT_PATH、[repository] MIRROR_QUEUE_LENGTH、[repository] PULL_REQUEST_QUEUE_LENGTH、[session] ENABLE_SET_COOKIE、[release.attachment] PATH、[webhook] QUEUE_LENGTH 等一批队列与路径类选项。0.13.0 还统一了默认分支为 main（本仓库当前 [repository] DEFAULT_BRANCH 以 conf/app.ini 实际值为准），并改为使用 Task 作为构建工具（见 Taskfile 相关配置 同目录的工程文件体系）。

升级路径红线：0.13.0 起 0.12 之前的数据库迁移脚本已被移除（CHANGELOG 明确警告）。任何停留在 0.12 之前的实例，必须先升到 0.12 完成迁移，再继续升级到 0.13+，切勿跨级直接升级。

六、安全增强的完整时间线（0.12 → 0.15 主线）

把散落在各版本的同类修复连成线，能看清 Gogs 安全模型的演进脉络：

1. 0.12.x：SSRF 治理起步——迁移（0.12.4 CRLF 注入、0.12.5、0.12.6 回归）与 webhook（0.12.8）的本地网络访问一律受 LOCAL_NETWORK_ALLOWLIST 约束；同期的 XSS（issue 指派者）、OS 命令注入（文件编辑器、上传）多轮修复；0.12.4 增加 X-Frame-Options 防点击劫持。
2. 0.13.x：把 DoS/路径穿越/2FA 绕过/越权删除等修成体系，Git LFS 与 webhook 交互（如 LFS 客户端 Content-Type 兼容）走向成熟。
3. 0.14.x：以“安全专版”形式补齐认证头信任边界（TRUSTED_PROXY_IPS）、SSH 握手超时、LFS 持有证明、notebook 渲染 XSS 链、API 令牌 Header-only，并在 0.14.1 完成纯 Go SQLite 与新一代 Docker 镜像铺垫。
4. 0.15.0+dev：移除 /install 引导、关闭默认注册、删除 CSRF 中间件与“记住我”Cookie（全部收敛到服务端会话）、下线 MSSQL/memcache/DSA/调试端点，Docker latest 语义重定义。

七、升级实操清单

综合全篇，将实例升级到 0.14.3+（推荐 0.15 系）时的检查项：

1. 配置底稿：在 custom/conf/app.ini 中完整重写，先按第五节对照表迁移所有旧配置项，删除已失效的 INSTALL_LOCK、DISABLE_HELO、CSRF_COOKIE_NAME、MSSQL [database] TYPE = mssql（需先迁库至 MySQL/PostgreSQL/SQLite3）与 memcache 缓存。
2. 密钥与默认值：更换 [security] SECRET_KEY；确认 [auth] DISABLE_REGISTRATION 符合预期（0.15 默认 true，需要开放注册时显式设 false）。
3. 代理与网络边界：若置于反向代理后，把代理节点 IP/CIDR 加入 [auth] TRUSTED_PROXY_IPS；需要访问内网做镜像/webhook 时，在 [security] LOCAL_NETWORK_ALLOWLIST 中显式放行目标主机名。
4. API 客户端改造：全部改用 Authorization 头携带访问令牌，移除 URL 中的 token/access_token。
5. 备份优先：升级前用 gogs backup（实现见 cmd/gogs/backup.go，可指定 --target 输出目录与 --archive-name）做全量备份，并确认能通过 cmd/gogs/restore.go 恢复。
6. 版本路径：若低于 0.12，先升 0.12 完成迁移再继续；编译源码请使用 Go 1.25+。
7. 安全公告跟进：文中 GHSA 编号（如 GHSA-w6j9-vw59-27wv、GHSA-qf6p-p7ww-cwr9、GHSA-3g28-2vwg-gxq6 等）均可作为检索关键词在安全公告库中核对受影响范围与披露细节，作为你所在团队风险评估的依据。

升级永远有成本，但对照 Gogs 这份 CHANGELOG 可以看到：0.14.3 与 0.15 的多数修复针对的是“已认证用户提权 / 任意文件写 / SSRF 进入内网”这类真实可利用的严重问题。对自托管 Git 服务而言，跟随本文件及时升级，本身就是最重要的安全配置。