# 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` | | 关闭通行密钥(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 选择顺序(重要) 改一个东西之前,按这个顺序选手段,维护成本递增: 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. 目录结构 ```text 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/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/`,然后重新生成: ```bash # 批量术语: 改 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 之后应用,用来收拾生硬的地方(如 `%d 张工单` → `共 %d 个 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 本地预览 ```bash 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" .}}`,所以**换认证源不用改模板**。 预览实例默认没有配置任何认证源,登录页就只显示管理员卡片。想看到统一身份认证那张卡, 临时加一个认证源即可(用完删掉): ```bash # 加: 用 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` 会建); - 一个都匹配不上就**整张卡片不显示**(宁可不显示, 也不给同学一个错的入口)。 预览里怎么看: ```bash ./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`: ```yaml 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` 增加: ```ini # 相对 deploy/ 目录解析; 也可写绝对路径 GITEA_CUSTOM_DIR=../customization/custom ``` 再在 `gitea` 的 `environment:` 里补上去 Gitea 化的元信息(也可以只改 `APP_NAME`): ```yaml 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`,部署在同一台机器的 `http://10.80.42.185/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` | > **改地址时要一起改的地方**:官网地址 `http://10.80.42.185/Website/` 在上表前三行的文件 > 与两个 `config.yaml` 里各出现一次;平台自身地址只在 > `scripts/settings.toml` 的 `gitea.public_url` 里维护一处(Issue 模板里的 > `{{BASE_URL}}` 在推送时替换)。 反向的入口(官网 → 平台)在 Website 仓库里,方案见 [`website-linkage.md`](website-linkage.md)。 ### 4.3 部署步骤 ```bash 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 http://10.80.42.185/QA/ | grep -c 课程答疑平台 # 5. 抽查首页 ``` > **⚠️ 权限坑(2026-09 生产真的挂过一次)**:`custom/` 是只读挂载,而容器里的 Gitea 以 > `git`(982)运行。编辑器/工具写出来的文件常是 `600`,只读挂载**不会**放宽权限检查, > 启动时直接: > ```text > [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 时的流程 ```bash # 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 模式下改动即生效(模板仍须重启) - ✅ 登录页改成「统一身份认证」优先 + 「管理员登录」卡片,表单仍可正常登录/报错 - ✅ 关闭 `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`)