官网改版后提问指南在 https://cpp.tongji.sh/Website/qa/ask/, 平台内不再单独留一份: - 删除 customization/custom/public/assets/tjhlp/ask-guide.html - home.tmpl(「按模板提问」卡片 + 底部相关站点)、base/head_navbar.tmpl(未登录导航 与用户菜单两处)、学期答疑入口卡片: 全部改指官网 /Website/qa/ask/ - issue-templates 两个 config.yaml 同样改指官网; general 里原来那条「答疑平台提问指南」 (指向平台内副本)直接去掉, 只剩「提问指南」+「课程官网」两条官网入口 - 顺手修掉两个已失效的官网地址: /Website/faq/ -> /Website/qa/faq/(旧的是跳转页), /Website/contact -> /Website/contact.html(旧地址现在 404) - custom/public 因此变成空目录, 加 .gitkeep 占位: bind mount 的源目录不存在时 docker compose 会以 root 创建它, 之后普通用户/CI 写不进去(同 options/.gitkeep 的坑) 断言同步: check.sh 与 preview.sh check 改为断言指向 /Website/qa/ask/、页面里没有 ask-question//Website/faq//Website/contact" 这些旧地址、平台内副本已 404。 实测(预览): 首页与导航栏 3 处 qa/ask/、1 处 qa/faq/、1 处 contact.html, 登录后卡片 再 2 处 qa/ask/; 两套检查脚本全过; scripts 80 个测试全过。
TJHLP 定制(Gitea 客制化)
本目录存放课程答疑平台对 Gitea 的定制:不改 Go 代码、不 fork、不重新编译,
只通过 Gitea 官方的 CustomPath 覆盖机制 + app.ini 配置项来做。
- 首页从「一款极易搭建的自托管 Git 服务」改成答疑平台介绍
- 中文术语调整(Issue 不再译成「工单」等)
- 去掉 Gitea 的自我推销(页脚 Powered by、meta、docs.gitea.com 外链)
当前基线:Gitea 1.27.3(见 gitea-version.txt,需与 deploy/.env 的
GITEA_VERSION 保持一致)。
1. 调查结论(机制)
以下结论来自 1.27.3 源码与实机验证,不是猜测。
1.1 覆盖原理:CustomPath 分层文件系统
Gitea 把模板 / 语言 / 静态资源都编进了二进制,但读取时走 assetfs.LayeredFS:
自定义层在前、内置层在后,同名文件自定义层优先;不存在「部分合并」——
覆盖一个文件就是整份替换(modules/assetfs/layered.go)。
| 内容 | 自定义层路径 | 内置层 | 生效方式 |
|---|---|---|---|
| 页面模板 | $CustomPath/templates/<相对路径> |
二进制内 embed | 启动时编译,重启生效 |
| 语言文件 | $CustomPath/options/locale/locale_*.json |
二进制内 embed | 启动时加载,dev 模式热加载 |
| 静态资源 | $CustomPath/public/assets/** |
二进制内 embed | 请求时读取,URL 前缀 /assets/ |
| 其它数据 | $CustomPath/options/{gitignore,label,license,readme}/... |
二进制内 embed | 按需读取 |
★ 最容易踩的坑:官方 Docker 镜像里
GITEA_CUSTOM=/data/gitea(docker inspect可见),所以定制文件对应的是/data/gitea/{templates,public,options}, 不是/data/gitea/custom/...。后者是「源码/二进制安装时WorkPath/custom」的习惯写法,在容器里挂了不会生效(实测无效)。
1.2 模板
- 落地页是
templates/home.tmpl;登录用户看到的是 Dashboard,落地页只对未登录访客 渲染(routers/web/home.go)。 - 想换首页有三种做法,成本从低到高:
- 配置:
[server] LANDING_PAGE = explore|organizations|login|/任意URL—— 直接不做落地页; - 模板:覆盖
custom/templates/home.tmpl(本目录采用的做法); - 加导航/页脚链接不需要覆盖整文件,用
custom/templates/custom/extra_links.tmpl、extra_links_footer.tmpl(内置就是空模板,属增量修改)。
- 配置:
- 模板在启动时编译:prod 下改完必须重启容器(官方文档同此说法)。 dev 模式会尝试热加载,但实测模板热加载不生效(语言文件可以),所以模板统一按 「改完重启」处理。
- 覆盖模板时不要动
{{...}}逻辑,只改文案/图标/链接;上游升级后要 diff 回来。
1.3 中文翻译
- 1.27 起语言文件是 JSON(
options/locale/locale_zh-CN.json,约 3900 个键)。 - 覆盖必须整份文件:非默认语言在加载时没有 en-US 兜底基座,而查不到键时会
退回默认语言(英文),不是退回中文
(
modules/translation/translation.go、i18n/localestore.go)。 只写几个键会导致整个界面大面积变英文。 - 因此本目录用
build.py从上游快照 + 我们的覆盖规则确定性生成整份文件, 人只需要维护overrides/下那几十行(详见 §3)。
1.4 能用配置解决的,别动模板
| 目标 | 配置项(app.ini) | Docker 环境变量 |
|---|---|---|
| 站点名 | 顶层 APP_NAME |
APP_NAME(裸变量,镜像模板用) |
| 首页指向 | [server] LANDING_PAGE |
GITEA__server__LANDING_PAGE |
| meta 作者/描述/关键词 | [ui.meta] AUTHOR/DESCRIPTION/KEYWORDS |
GITEA__ui_0X2E_meta__DESCRIPTION 等 |
| 页脚 Powered by / 版本号 | [other] SHOW_FOOTER_POWERED_BY / SHOW_FOOTER_VERSION |
GITEA__other__SHOW_FOOTER_POWERED_BY |
| 自定义主题配色 | [ui] THEMES + custom/public/assets/css/theme-*.css |
GITEA__ui__THEMES |
| 关闭通行密钥(WebAuthn) | [service] ENABLE_PASSKEY_AUTHENTICATION |
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION |
| 关闭用户名/密码表单 | [service] ENABLE_PASSWORD_SIGNIN_FORM |
GITEA__service__ENABLE_PASSWORD_SIGNIN_FORM |
| Logo / favicon | 放 custom/public/assets/img/{logo,favicon}.svg 等 |
同上(文件方式) |
环境变量规则:
GITEA__<段名>__<键名>,段名里的.不能直接写,要编码成_0X2E_,所以[ui.meta]是GITEA__ui_0X2E_meta__...(modules/setting/config_env.go)。
1.5 选择顺序(重要)
改一个东西之前,按这个顺序选手段,维护成本递增:
- app.ini / 环境变量(无文件、升级无感)
custom/templates/custom/extra_*.tmpl(增量追加,不覆盖上游文件)custom/options/数据文件覆盖(语言、labels…)- 整文件覆盖内置模板(本目录的
custom/templates/home.tmpl、base/head_navbar.tmpl) - 自建镜像 / fork 改 Go 代码 —— 只有在需要改逻辑或前端资源时才考虑,本阶段不需要
2. 目录结构
customization/
├── README.md 本文件
├── gitea-version.txt 基线版本(与 deploy/.env 的 GITEA_VERSION 同步)
├── build.py 生成 locale + 规范 custom/ 权限(容器用户要能读)
├── fetch-upstream.sh 拉取上游文件快照(升级时用)
├── upstream-files.txt 需要留快照的上游文件清单
├── upstream/<版本>/... 上游基线,只读参考,由脚本生成
├── overrides/ ★ 只维护这里
│ ├── locale_zh-CN.rules.json 批量字面替换(如「工单」→「Issue」)
│ └── locale_zh-CN.json 精确到键的覆盖(优先于 rules)
├── custom/ ★ 挂进容器的覆盖层(= $CustomPath 的内容)
│ ├── templates/home.tmpl 落地页
│ ├── templates/base/head_navbar.tmpl 导航栏(去掉 docs.gitea.com)
│ ├── templates/user/auth/signin.tmpl 登录页(统一身份认证优先, 管理员登录次要)
│ ├── templates/user/dashboard/dashboard.tmpl 首页(登录后); 只比上游多一行 include
│ ├── templates/custom/tjhlp_semester_card.tmpl ★ 首页顶部的学期答疑入口卡片(自己写的)
│ ├── public/.gitkeep 占位(提问指南已只在官网, 目录留作将来放静态资源)
│ └── options/locale/locale_zh-CN.json 生成物,已 gitignore
└── preview/ 本地预览(独立 compose,独立端口/数据)
├── compose.yaml
├── preview.sh
└── data/ 预览数据,已 gitignore
custom/ 与 $CustomPath 的结构一一对应;custom/options/locale/*.json 是生成物,
不要手改(build.py --check 会检查是否与 overrides 一致)。
3. 改东西的日常流程
3.1 改中文翻译
只动 overrides/,然后重新生成:
# 批量术语: 改 overrides/locale_zh-CN.rules.json
# 个例精修: 改 overrides/locale_zh-CN.json(键必须在同版本上游存在,否则构建报错)
python3 customization/build.py # 会打印每一处改动
python3 customization/build.py --check # CI/部署前校验生成物是否最新
约定:
rules是字面替换,会自动在中英交界处补空格(基于工单列表→基于 Issue 列表);overrides在 rules 之后应用,用来收拾生硬的地方(如<strong>%d</strong> 张工单→共 <strong>%d</strong> 个 Issue);- 含占位符(
%s/%[1]s/%d)的条目会校验占位符是否被改坏,改坏直接构建失败; - 覆盖键在上游不存在会报错 —— 这是升级时发现「上游删了/改了键名」的保护。
3.2 改页面
- 先把上游基线 diff 一遍,确认结构没变:
diff upstream/<版本>/templates/home.tmpl custom/templates/home.tmpl - 在
custom/templates/...里改文案/图标/链接; - 新增一个要覆盖的模板时,把它加进
upstream-files.txt,再跑customization/fetch-upstream.sh <版本>留下基线。
3.3 本地预览
customization/preview/preview.sh up # 启动,http://127.0.0.1:2081
customization/preview/preview.sh logs # 看日志
customization/preview/preview.sh reload # 改完模板/生成语言文件后重启
customization/preview/preview.sh check # 自动校验: 首页文案/页脚/meta/静态页/术语
customization/preview/preview.sh admin # 建管理员(验证登录后页面,如 Issue 列表)
customization/preview/preview.sh reset # 清空预览数据重新来
预览实例与生产完全隔离:项目名 gitea-preview、容器 gitea-preview、
端口只绑 127.0.0.1:2081、数据库用 sqlite、数据在 preview/data/(删掉即重置)。
用的是与生产相同的镜像版本,所以渲染结果一致。
RUN_MODE默认dev:语言文件改动会自动热加载(实测),模板报错也不致命;PREVIEW_RUN_MODE=prod ./preview.sh up可切到与生产一致的严格模式。- 模板改动仍需重启(
reload),这是 Gitea 的既有行为。 - 需要 docker 权限;当前 shell 不在 docker 组时脚本会自动改用
sg docker -c。
3.4 登录页
登录页 custom/templates/user/auth/signin.tmpl 的结构是「统一身份认证(第一张卡) +
管理员登录(第二张卡)」,认证源那部分直接复用上游的
{{template "user/auth/external_auth_methods" .}},所以换认证源不用改模板。
预览实例默认没有配置任何认证源,登录页就只显示管理员卡片。想看到统一身份认证那张卡, 临时加一个认证源即可(用完删掉):
# 加: 用 github 这类不需要 discovery 的 provider 最省事, 只为看布局
sg docker -c "docker exec -u git gitea-preview gitea admin auth add-oauth \
--name '高程统一身份认证(测试)' --provider github --key k --secret s"
sg docker -c 'docker exec -u git gitea-preview gitea admin auth list' # 看 ID
sg docker -c 'docker exec -u git gitea-preview gitea admin auth delete --id 1'
通行密钥(WebAuthn)已关闭,不是靠模板删的,而是配置:
[service] ENABLE_PASSKEY_AUTHENTICATION = false(两处 compose 都设了)。
上游那块在浏览器不支持条件中介时会渲染成一个空的方框,关掉配置连区块都不再输出。
3.5 首页(登录后)的「本学期答疑入口」卡片
登录后首页上游会给贡献热力图、最近活动、仓库列表, 对只来提问的同学是干扰。 我们在页面顶部加了一张约 1/3 屏高的卡片, 里面一个按钮直接跳到本学期答疑区。
涉及两个文件:
| 文件 | 作用 |
|---|---|
custom/templates/user/dashboard/dashboard.tmpl |
覆盖上游同名模板, 只比上游多一行 {{template "custom/tjhlp_semester_card" .}}(插在 navbar 之后、flex-container 之前) |
custom/templates/custom/tjhlp_semester_card.tmpl |
卡片本身(本课程自己写的, 上游没有这个文件) |
判定与规则(都在卡片文件里, 改它就行):
- 数据来自
.Orgs—— 当前登录用户所属的全部组织(routers/web/user/home.go的 Dashboard 注入); - 「学期组织」= 名字形如
tjhlp-<5 位数字>:tjhlp-26271表示 26|27|1 → 2026-2027 学年第一学期; 旧命名tjhlp-2026s(带字母)不认, 其它前缀(course-team)也不认; - 同时匹配多个时取名字最大的(即最新学期), 所以同学同时在上学期/本学期组织里也只会看到本学期;
- 按钮指向
{{AppSubUrl}}/<学期组织>/general/issues—— 依赖「每个学期组织都有一个general仓库」这个约定(tjhlp setup init会建); - 一个都匹配不上就整张卡片不显示(宁可不显示, 也不给同学一个错的入口)。
预览里怎么看:
./preview.sh admin # 先有管理员(仅首次)
./preview.sh semester # 建 tjhlp-26271 + general 仓库, 创建者即成员
# 想验证筛选规则, 再建几个干扰项: 旧的 tjhlp-25261 / 带字母的 tjhlp-2026s
./preview.sh semester previewadmin previewadmin123 tjhlp-2026s
# 然后浏览器登录 http://127.0.0.1:2081 (previewadmin / previewadmin123) 看首页
./preview.sh check 会自动登录 previewadmin 抓一次首页, 断言卡片存在、按钮指向
<学期组织>/general/issues、高度是 33vh。
4. 纳入当前项目 & 部署
4.1 改动点(已在 deploy/ 落地)
deploy/compose.yaml 的 gitea 服务增加了三行只读挂载(注意目标是
/data/gitea/...,不是 /data/gitea/custom/...),deploy/.env 与
.env.example 增加了 GITEA_CUSTOM_DIR=../customization/custom:
volumes:
- ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data
# 定制覆盖层: 官方镜像 GITEA_CUSTOM=/data/gitea
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
deploy/.env 增加:
# 相对 deploy/ 目录解析; 也可写绝对路径
GITEA_CUSTOM_DIR=../customization/custom
再在 gitea 的 environment: 里补上去 Gitea 化的元信息(也可以只改 APP_NAME):
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
GITEA__ui_0X2E_meta__DESCRIPTION: 同济大学高级语言程序设计课程答疑平台
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false"
设计取舍:
- 只读挂载:定制内容是仓库里的源码,容器不应回写;
conf/、log/等仍在/data/gitea里由容器自己管理,互不影响。 - 挂三个子目录而不是整个
custom/:避免遮住同级的conf/、log/。 - 镜像 entrypoint 会做
chown -R git:git /data/gitea,只在属主不是git时执行; 现有/srv/gitea/gitea属主已是git(982),不会碰到只读挂载。 - 定制只影响渲染,不碰数据库和仓库,回滚 = 去掉挂载 + 重启。
4.2 与课程官网联动
课程官网(VitePress 项目 tjhlp-website,部署在同一台机器的 https://cpp.tongji.sh/Website/)
与答疑平台互为入口。平台侧已经落地的入口:
| 位置 | 内容 | 文件 |
|---|---|---|
| 导航栏(未登录) | 「课程官网」/「提问指南」 | custom/templates/base/head_navbar.tmpl |
| 用户菜单(已登录) | 「课程官网」/「提问指南」 | 同上 |
| 首页「按模板提问」卡片 | 官网《提问指南》 | custom/templates/home.tmpl |
| 首页底部「相关站点」 | 官网 / 提问指南 / 常见问题 / 联系我们 | 同上 |
| 首页答疑入口卡片 | 官网《提问指南》 | custom/templates/custom/tjhlp_semester_card.tmpl |
| 新建 Issue 页的引导链接 | 提问指南 / 课程官网 | issue-templates/*/.gitea/ISSUE_TEMPLATE/config.yaml |
官网地址 https://cpp.tongji.sh/Website/ 出现在上表列出的模板与两个 config.yaml 里;
平台自身地址只在 scripts/settings.toml 的 gitea.public_url 里维护一处(Issue 模板里的
{{BASE_URL}} 在推送时替换)。
提问指南只在官网保留一份(
/Website/qa/ask/):平台内原来的副本custom/public/assets/tjhlp/ask-guide.html已在 2026-09 删除, 相关链接全部指向官网。 官网 2026-09 改版后的路径: 提问指南/Website/qa/ask/、常见问题/Website/qa/faq/、 联系我们/Website/contact.html; 旧的/Website/ask-question/、/Website/faq/只是跳转页,/Website/contact已经 404 —— 不要再写这些旧地址。
反向的入口(官网 → 平台)在 Website 仓库里,方案见
website-linkage.md。
4.3 部署步骤
cd deploy
python3 ../customization/build.py # 1. 重新生成 + 规范 custom/ 权限(见下)
python3 ../customization/build.py --check # (可选)校验生成物与权限
./scripts/backup.sh # 2. 例行备份(内容定制其实不影响数据)
# 3. 应用 compose/.env 改动后(会重建容器)
docker compose up -d
# 只改了 custom/ 里的内容(无 compose 变化)时:
# docker compose restart gitea
sudo ./scripts/verify.sh # 4. 体检
curl -s https://cpp.tongji.sh/QA/ | grep -c 课程答疑平台 # 5. 抽查首页
⚠️ 权限坑(2026-09 生产真的挂过一次):
custom/是只读挂载,而容器里的 Gitea 以git(982)运行。编辑器/工具写出来的文件常是600,只读挂载不会放宽权限检查, 启动时直接:[F] Gitea can't run with template errors: open home.tmpl: permission denied然后
Restarting死循环。预览环境不会暴露它 —— 预览容器的 uid 就是宿主用户 (PREVIEW_UID),同一属主当然读得到。build.py每次都会把custom/补齐成「组/其他人可读,目录可进入」,--check也会在 不可读时报错退出,所以部署前跑一次build.py就不会中招。 手工体检:docker compose exec -T -u git gitea head -c1 /data/gitea/templates/home.tmpl。
回滚:去掉挂载与环境变量 → docker compose up -d;或 git revert 本目录改动 →
docker compose restart gitea。
4.4 升级 Gitea 时的流程
# 1. 同步版本号: customization/gitea-version.txt 与 deploy/.env 的 GITEA_VERSION
# 2. 拉上游快照
customization/fetch-upstream.sh 1.28.0
# 3. 看上游改了什么,特别是我们整文件覆盖过的模板
git diff customization/upstream/
# 4. 把上游的结构性改动合并进 custom/templates/**.tmpl
# 5. 重新生成语言文件(上游新增的键会自动带进来)
python3 customization/build.py
# 6. 预览验证
customization/preview/preview.sh up && customization/preview/preview.sh check
# 7. 备份 + 升级(与 deploy/README.md §7.1 一致)
cd deploy && ./scripts/backup.sh --quiesce && docker compose pull gitea && docker compose up -d gitea
build.py 会在「我们覆盖的键在新版本里不存在」「占位符对不上」时直接失败,
把升级风险挡在部署之前。
5. 已验证 / 未覆盖
已在本机实测(官方 1.27.3 镜像 + 独立预览实例):
- ✅ 落地页替换为定制
home.tmpl(4 张卡片、无 Gitea 功能介绍) - ✅
[ui.meta]元信息替换(GITEA__ui_0X2E_meta__*编码有效) - ✅ 页脚 Powered by / 版本号可关闭
- ✅ 导航栏
docs.gitea.com外链替换为官网《提问指南》(/Website/qa/ask/) - ✅ 平台内
public/assets/tjhlp/ask-guide.html已删除, 页面与 Issue 模板全部指向官网 - ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」
- ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启)
- ✅ 登录页改成「统一身份认证」优先 + 「管理员登录」卡片,表单仍可正常登录/报错
- ✅ 关闭
ENABLE_PASSKEY_AUTHENTICATION后,登录页不再出现空的通行密钥方框 - ✅ 首页(登录后)顶部出现学期答疑入口卡片: 只认
tjhlp-<5 位数字>、取最新学期、 无匹配则不显示(预览里用 3 个用户 × 4 个组织验证过)
尚未覆盖(需要时按同样套路加):
- Logo / favicon 换成本课程的图(需要设计稿;放到
custom/public/assets/img/) - 注册页(
user/auth/signup.tmpl)、错误页文案 - 更多术语(合并请求 / 仓库 / 里程碑…)—— 在
overrides/里加规则即可 - 自定义主题配色(
[ui] THEMES+custom/public/assets/css/theme-*.css)