Files
tjhlp-gitea/customization
admin 7d19e2729c feat: 新增 Gitea 定制机制(首页/中文语言/去 Gitea 化)与本地预览
不改 Go 代码、不 fork, 只用官方 CustomPath 覆盖层 + app.ini/env 配置:

- custom/templates: 整文件覆盖 home.tmpl(落地页换成答疑平台介绍)与
  base/head_navbar.tmpl(docs.gitea.com -> 站内提问指南、新增课程官网入口)
- custom/public/assets/tjhlp/ask-guide.html: 站内提问指南静态页
- overrides/ + build.py: 由上游快照确定性生成整份 locale_zh-CN.json
  (工单 -> Issue 等 133 处), 带占位符校验; 缺失键会退回英文, 必须整份覆盖
- build.py 同时负责规范 custom/ 权限: 容器内 Gitea 以 git(982) 运行,
  文件若为 600 只读挂载也会 permission denied 并拒绝启动(生产踩过)
- upstream/<版本>/ + fetch-upstream.sh: 上游基线, 供升级时 diff 与重生成
- preview/: 独立 compose + preview.sh(up/check/reload/admin/reset),
  与生产隔离(独立端口 2081/数据目录/sqlite), 用同一镜像版本验证效果
- website-linkage.md: 官网(VitePress)侧的联动改动提案
2026-09-11 17:07:05 +08:00
..

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)。
  • 想换首页有三种做法,成本从低到高:
    1. 配置:[server] LANDING_PAGE = explore|organizations|login|/任意URL —— 直接不做落地页;
    2. 模板:覆盖 custom/templates/home.tmpl(本目录采用的做法);
    3. 加导航/页脚链接不需要覆盖整文件,用 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
Logo / favicon 放 custom/public/assets/img/{logo,favicon}.svg 等 同上(文件方式)

环境变量规则:GITEA__<段名>__<键名>,段名里的 . 不能直接写,要编码成 _0X2E_,所以 [ui.meta] 是 GITEA__ui_0X2E_meta__... (modules/setting/config_env.go)。

1.5 选择顺序(重要)

改一个东西之前,按这个顺序选手段,维护成本递增:

  1. app.ini / 环境变量(无文件、升级无感)
  2. custom/templates/custom/extra_*.tmpl(增量追加,不覆盖上游文件)
  3. custom/options/ 数据文件覆盖(语言、labels…)
  4. 整文件覆盖内置模板(本目录的 custom/templates/home.tmpl、base/head_navbar.tmpl)
  5. 自建镜像 / 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)
│   ├── public/assets/tjhlp/ask-guide.html   静态「提问指南」页(/assets/tjhlp/...)
│   └── 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 改页面

  1. 先把上游基线 diff 一遍,确认结构没变: diff upstream/<版本>/templates/home.tmpl custom/templates/home.tmpl
  2. 在 custom/templates/... 里改文案/图标/链接;
  3. 新增一个要覆盖的模板时,把它加进 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。

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/public/assets/tjhlp/ask-guide.html
新建 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 仓库里,方案见 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 外链替换为课程提问指南(整文件覆盖 head_navbar.tmpl)
  • ✅ custom/public/assets/tjhlp/ask-guide.html 经 /assets/ 正常访问
  • ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」
  • ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启)

尚未覆盖(需要时按同样套路加):

  • Logo / favicon 换成本课程的图(需要设计稿;放到 custom/public/assets/img/)
  • 登录页、注册页、错误页文案
  • 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 overrides/ 里加规则即可
  • 自定义主题配色([ui] THEMES + custom/public/assets/css/theme-*.css)