摘要：
半夜里，趁着配置成功的兴头写下了《手把手教你Caddy2反向代理Gitea》。一觉醒来，回看文章满眼全是废话。其实总结最终的成功设置，上配置要点... 半夜里，趁着配置成功的兴头写下了《手把手教你Caddy2反向代理Gitea》。一觉醒来，回看文章满眼全是废话。其实总结最终的成功设置，上配置要点和配置项即可。这一步步、手把手的，凭什么让读者把我踩坑的过程重复一遍？
这是一篇回顾安装部署踩坑的文章。想直接跳到正确安装部署文件的，可以直接阅读这篇《Docker环境下Caddy2反向代理Gitea配置总结》。
话说回来，本该简单且在其他应用里重复过多次的配置形式，为什么会在这次Gitea的安装部署中搞那么繁杂？配置为什么会不断失败？为什么最终非要搞成小孩学步似的，小步前进，遇挫回退再迂回，最后才发现胜利的彼岸？
回顾整个部署探究过程，发现这里有对Caddy2配置尚不熟练的缘故，但是关键的坑来自于Gitea的文档和它的奇葩表现。由于没有仔细探究其代码，暂时无法从源码级别来揭示这个奇怪现象。
先说说官方文档的坑。
Gitea的缺省部署模式，其web服务侦听在3000端口，访问地址是：:3000。但这个显然不符合大部分生产开发环境的实际情况。大部分的实际情况是：
希望地址更优雅些，把端口号3000去掉；希望通过https访问，更安全一些；想使用的域名，其根路径已经部署了其他应用或网站，如果希望配置在这个域名下，必须使用子路径来访问Gitea服务。当然，如果在第3步里，你恰好不想用子路径来访问，而是可以使用某域名的根路径，哪怕你用的是个多级域名，你可能都不会踩到这个大坑。所以，使用域名的根路径来部署，是安装成功的最佳选项。
如果上面的情况成立，那么就必须使用到Gitea的带路径配置，参见官方文档：使用：反向代理 - Docs中的“使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径”，也就是把Gitea的访问地址，从:3000（或者），配置成。这中间的跨度涉及到了改3000端口（实际上不用改）、改https支持、改子路径、考虑先安装还是先改配置（必须先安装，再改配置，否则看到配置后的错误提示页会先让你质疑这次的安装是否成功）。
需要指出的是，上面这篇官方的中文版指导文档中的Caddy配置，只适用于caddy1，如果你使用的是Caddy2并自以为得到了精髓，随手就把proxy按照reverse_proxy的语法来修改，参见中文版文档：
git.example.com {
# 注意: 路径 /git/ 最后需要有路径符号
proxy /git/ http://localhost:3000
}那么很不幸你掉进了第一个大坑且无法自我意识到。为了反复尝试这个配置选项，你会碰上其他大坑。考虑到语法的正确性和官方文档的权威性，你最终只会在不断的失败中一步步走向对自己的无尽怀疑而放弃这次的安装部署。
适用于Caddy2的正确方法，是在配置里使用route、uri等directives。关于这个的正确描述，官方文档里面存在，只是不存在于中文版。我在事后翻阅了Gitea在线文档的英文版本，发现同样是对应了中文版中的《反向代理》使用：反向代理 - Docs章节的英文版《Reverse Proxies》Reverse Proxies - Docs，其中关于“Caddy with a sub-path”的环节，描述的正是：
git.example.com {
route /git/* {
uri strip_prefix /git
reverse_proxy localhost:3000
}
}虽然没有对这段配置做caddy的版本限定，但是在这段配置的下方提供了另外一个与中文版中同样的配置内容，上方注明：“Or, for Caddy v1:”。所以，只有上面这段配置才是在Caddy2下的正确打开方式。
所以，这踩到的第一个大坑来自于中文版官方文档的安装参考。这一点，不知道Gitea自己是否知道。如果有关人员能看到这一点，希望你们能对此做些修正。
再说说部署尝试的过程中，Gitea的不同奇葩表现。
看过上面文档一使用：反向代理 - Docs以后，你一定信心满满直奔Caddy环节，按照文档的要求去修改Caddy配置。然后你困惑了：接下来，是在gitea的缺省配置下，先在3000端口上安装好Gitea然后再去修改Gitea的配置呢？还是先直奔Gitea的配置目录，修改app.ini，再来安装？
先说答案：都可以，只是不同的方式下你会碰到不同的奇葩表现。
首先缺省情况下，如果Gitea容器尚未被启动，你是不可能在挂载的Gitea数据目录里看到gitea/conf/app.ini这个配置文件，所以你不会动这个念头。
但是，你很有可能会处于已经启动了Gitea容器，但是还没有打开浏览器进行Gitea安装的情况。这时候，你面临着先该配置再重启容器安装，还是先缺省安装再改配置的选择。
很不幸，官方文档里并没有给出这样的指导。于是你想，大不了硬着头皮两个都试下呗。
于是，在中文文档的错误指引下，你试了先改app.ini，在里面修改了ROOT_URL=https://domain.com/sub-path/。这个过程中你会反复怀疑，里面的端口号要不要改？域名要不要改？可能都会尝试一遍，无非是增加了出错后的排错复杂度。
然后，你会发现在Gitea的日志里，出现"Get /sub-path/ for 1.2.3.4 404 Not Found in 1.4ms @ web/goget.go:20(web.goGet)"这样的提示，或者类似"install script not found"之类的提示。但是却在日志里清晰地看到，Gitea启动时有“Listen: :3000/sub-path”、“AppURL(ROOT_URL): ”的字样。
而浏览器端的表现，大部分情况下，你看到页面文字出来了，但是图片、LOGO、资源文件都没有加载。浏览器上检查元素，发现凡是带“/sub-path/”路径的资源，都加载失败。
结论是：ROOT_URL似乎生效了，但是似乎又没有生效。这种矛盾的现象和心情，伴随着你整个的部署过程。于是你会不断地尝试修改ROOT_URL、修改Caddy的reverse_proxy路径，将二者进行组合排列做部署尝试。然后你最成功的时候会发现，第一个页面成功了，但是上面所有的下级链接完全错误。
为什么会这样？其实这就是Gitea的奇葩表现：根页面的路径，与子页面的路径处理似乎不在一个层级。错误的配置，也可能出现根页面部分显示，或者根页面全部正确显示但是下级页面根本不显示。这种不一致的表现让你的心情像备胎一样的抓狂，但是你伸手却什么也抓不完整。直到你坚定地在caddy2里用route+uri stripe_prefix来处理反向代理和路径去除，并在Gitea里毫不犹豫地在ROOT_URL中加上Caddyfile里去除的路径prefix：sub-path。然后你就突然跳出了大坑们。
针对这个环节的奇葩表现，对Caddy2+Gitea的配置：将Gitea路由至一个子路径的情况，对app.ini的server区段做一个简单说明：
[server]
APP_DATA_PATH = /data/gitea # 正常配置，可以不修改
DOMAIN = example.com # 缺省安装过程中添加；后期修改也可以
SSH_DOMAIN = example.com # 与ssh相关，与本次部署中的WEB访问关系不大
HTTP_PORT = 3000 # gitea作为后端运行的容器，这个端口号可以不改。也不需要体现在下面的链接里
ROOT_URL = https://example.com/sub-path/ # 可以直接写https；可以在缺省安装中页面填写；可以缺省安装页面不填写但是安装完毕后改app.ini
DISABLE_SSH = false
SSH_PORT = 22
SSH_LISTEN_PORT = 22
LFS_START_SERVER = true
LFS_JWT_SECRET = GM-EoJmU27V8sbTs8v-EPwXpA2f3wz5krICk4zeAtZc
OFFLINE_MODE = false相关文章：
《Docker环境下Caddy2反向代理Gitea配置总结》《手把手教你使用Caddy2反向代理部署Gitea》
