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)侧的联动改动提案
This commit is contained in:
2026-09-11 17:07:05 +08:00
parent 79256c5be0
commit 7d19e2729c
18 changed files with 5513 additions and 0 deletions
+4
View File
@@ -18,6 +18,10 @@ credentials_*.csv
deploy/.env deploy/.env
deploy/backups/ deploy/backups/
# Customization
customization/custom/options/locale/locale_zh-CN.json
customization/preview/data/
# IDE # IDE
.idea/ .idea/
.vscode/ .vscode/
+14
View File
@@ -18,6 +18,7 @@
```text ```text
tjhlp-gitea/ tjhlp-gitea/
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL) ├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览
├── issue-templates/ Issue 模板(按仓库类型区分) ├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具 └── scripts/ Python CLI 管理工具
``` ```
@@ -116,6 +117,19 @@ sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反
yamllint issue-templates/ # YAML 语法 yamllint issue-templates/ # YAML 语法
``` ```
### 定制(Gitea 客制化)
```bash
python3 customization/build.py # 生成定制语言文件
python3 customization/build.py --check # 校验生成物是否最新
customization/preview/preview.sh up # 起本地预览(127.0.0.1:2081)
customization/preview/preview.sh check # 自动校验首页/页脚/meta/术语
```
机制调查、日常改法与部署/升级流程见 [`customization/README.md`](customization/README.md);
与课程官网(<https://cpp.tongji.sh/Website/>)的互相导流见
[`customization/website-linkage.md`](customization/website-linkage.md)。
详见各子目录的 README。 详见各子目录的 README。
## 技术栈 ## 技术栈
+304
View File
@@ -0,0 +1,304 @@
# 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. 目录结构
```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)
│ ├── 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 之后应用,用来收拾生硬的地方(如 `<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 本地预览
```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`。
---
## 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`,部署在同一台机器的 `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`](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 https://cpp.tongji.sh/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 模式下改动即生效(模板仍须重启)
尚未覆盖(需要时按同样套路加):
- Logo / favicon 换成本课程的图(需要设计稿;放到 `custom/public/assets/img/`)
- 登录页、注册页、错误页文案
- 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 `overrides/` 里加规则即可
- 自定义主题配色(`[ui] THEMES` + `custom/public/assets/css/theme-*.css`)
+202
View File
@@ -0,0 +1,202 @@
#!/usr/bin/env python3
"""生成 TJHLP 定制用的 Gitea 简体中文语言文件。
Gitea 只支持「整个文件覆盖」locale: 放在 custom/options/locale/locale_zh-CN.json 的
文件会完全替换内置的 zh-CN。缺失的键不会退回中文, 而是退回默认语言(en-US),
所以覆盖文件必须是完整的一份, 不能只写改动项。本脚本用来从上游快照
(upstream/<版本>/locale_zh-CN.json) + 我们的覆盖(rules / overrides)确定性地产出
这份完整文件, 避免手工维护 3900 个键。
用法:
python3 customization/build.py # 生成 custom/options/locale/locale_zh-CN.json
python3 customization/build.py --check # 只校验磁盘上的生成物是否最新(CI / 部署前)
python3 customization/build.py --quiet # 不打印改动清单
除了生成语言文件, 本脚本还负责把 custom/ 的权限规范成「容器用户可读」——
Gitea 容器以镜像内的 git 用户运行, 而编辑器写出来的文件可能是 600, 只读挂载进容器后
会 permission denied 并让 Gitea 拒绝启动(见 deploy/README.md 已知陷阱 3)。
"""
from __future__ import annotations
import argparse
import json
import re
import stat
import sys
from pathlib import Path
HERE = Path(__file__).resolve().parent
CUSTOM_DIR = HERE / "custom"
OUT_PATH = CUSTOM_DIR / "options" / "locale" / "locale_zh-CN.json"
# Go 模板/printf 里的格式化占位符, 例如 %s %d %v %[1]s %[2]d %%
FORMAT_RE = re.compile(r"%(?:\[(\d+)\])?[-+# 0-9.]*[a-zA-Z%]")
def load_json(path: Path):
with path.open(encoding="utf-8") as f:
return json.load(f)
def strip_comments(obj: dict) -> dict:
"""去掉以 _ 开头的说明键, 它们只是给人看的元数据。"""
return {k: v for k, v in obj.items() if not k.startswith("_")}
def format_verbs(text: str) -> list[str]:
return FORMAT_RE.findall(text)
def _is_cjk_ideograph(ch: str) -> bool:
# 只在汉字旁边补空格; 中文标点(。,、「」…)本身不需要与英文分隔
return "\u4e00" <= ch <= "\u9fff"
def _pad_for(edge: str, neighbour: str) -> str:
"""中英混排时给替换结果补一个空格: 汉字紧邻英文/数字才需要。"""
if edge and edge[0].isascii() and edge[0].isalnum() and neighbour and _is_cjk_ideograph(neighbour):
return " "
return ""
def apply_rule(text: str, src: str, dst: str) -> str:
"""字面替换 src -> dst, 并在中英交界处补空格(工单 -> " Issue ")。"""
out: list[str] = []
pos = 0
while True:
found = text.find(src, pos)
if found < 0:
out.append(text[pos:])
return "".join(out)
out.append(text[pos:found])
left = text[found - 1] if found > 0 else ""
right = text[found + len(src)] if found + len(src) < len(text) else ""
out.append(_pad_for(dst, left) + dst + _pad_for(dst[::-1], right))
pos = found + len(src)
def build() -> tuple[dict, dict, list[tuple[str, str, str]]]:
version = (HERE / "gitea-version.txt").read_text(encoding="utf-8").strip()
upstream_path = HERE / "upstream" / version / "options" / "locale" / "locale_zh-CN.json"
if not upstream_path.exists():
sys.exit(f"缺少上游快照: {upstream_path} (先执行 customization/fetch-upstream.sh {version})")
upstream: dict[str, object] = load_json(upstream_path)
locale: dict[str, object] = dict(upstream)
rules = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.rules.json"))["rules"]
overrides = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.json"))["overrides"]
errors: list[str] = []
for rule in rules:
src, dst = rule["from"], rule["to"]
for key, value in locale.items():
if isinstance(value, str) and src in value:
locale[key] = apply_rule(value, src, dst)
for key, new_value in overrides.items():
if key not in upstream:
errors.append(f"覆盖键不存在于上游: {key}")
continue
old_value = upstream[key]
if not isinstance(old_value, str):
errors.append(f"覆盖键在上游不是字符串: {key}")
continue
if format_verbs(old_value) != format_verbs(new_value):
errors.append(f"占位符不一致: {key}\n 上游: {old_value}\n 覆盖: {new_value}")
locale[key] = new_value
if errors:
sys.exit("构建失败:\n - " + "\n - ".join(errors))
changes = [(k, str(upstream[k]), str(v)) for k, v in locale.items() if upstream.get(k) != v]
return locale, upstream, changes
def render(locale: dict) -> str:
# 保持上游的键顺序, 让 git diff 只显示真正改动的行
return json.dumps(locale, ensure_ascii=False, indent=2) + "\n"
# ---------------------------------------------------------------------------
# custom/ 的权限
# ---------------------------------------------------------------------------
# Gitea 容器以镜像内的 git 用户运行(部署里 USER_UID=982), 而编辑器/工具写出来的文件
# 可能是 600(仅属主可读)。custom/ 是只读挂载进容器的, 一旦容器用户读不到,
# prod 模式会直接拒绝启动: "Gitea can't run with template errors: open home.tmpl:
# permission denied"(2026-09 生产真的这样挂过一次)。预览之所以没暴露, 是因为
# 预览容器的 uid 就是宿主用户。
# 所以每次生成都顺手把 custom/ 规范成「组 + 其他人可读, 目录可进入」。
def unreadable_paths(root: Path) -> list[Path]:
"""列出容器用户(非属主)读不到的文件/进不去的目录。"""
bad: list[Path] = []
for path in sorted(root.rglob("*")):
mode = path.stat().st_mode
need = stat.S_IROTH | (stat.S_IXOTH if path.is_dir() else 0)
if mode & need != need:
bad.append(path)
return bad
def ensure_readable(root: Path) -> list[Path]:
"""补齐 g+r / o+r(目录再补 o+x), 返回被修正的路径。"""
fixed: list[Path] = []
for path in sorted(root.rglob("*")):
mode = path.stat().st_mode
want = mode | stat.S_IRGRP | stat.S_IROTH
if path.is_dir():
want |= stat.S_IXGRP | stat.S_IXOTH
if want != mode:
path.chmod(want)
fixed.append(path)
return fixed
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--check", action="store_true", help="只校验, 不写入")
parser.add_argument("--quiet", action="store_true", help="不打印改动清单")
args = parser.parse_args()
locale, upstream, changes = build()
rendered = render(locale)
if not args.quiet:
print(f"上游键数: {len(upstream)} 覆盖后键数: {len(locale)} 改动: {len(changes)} 处")
for key, old, new in changes:
print(f" {key}\n - {old}\n + {new}")
if args.check:
current = OUT_PATH.read_text(encoding="utf-8") if OUT_PATH.exists() else ""
if current != rendered:
print(f"✗ {OUT_PATH} 与覆盖配置不一致, 请运行 python3 customization/build.py", file=sys.stderr)
return 1
print(f"✓ {OUT_PATH} 是最新的")
bad = unreadable_paths(CUSTOM_DIR)
if bad:
print(
"✗ 下列文件/目录对容器用户不可读(挂载进容器会 permission denied), "
"请运行 python3 customization/build.py 修正:",
file=sys.stderr,
)
for path in bad:
print(f" {path.relative_to(HERE)} {oct(path.stat().st_mode & 0o777)}", file=sys.stderr)
return 1
print("✓ custom/ 权限正常(容器用户可读)")
return 0
OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
OUT_PATH.write_text(rendered, encoding="utf-8")
print(f"✓ 已生成 {OUT_PATH}")
fixed = ensure_readable(CUSTOM_DIR)
if fixed:
print(f"✓ 修正了 {len(fixed)} 个权限过紧的路径(容器用户需要可读):")
for path in fixed:
print(f" {path.relative_to(HERE)}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,88 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>提问指南 - 同济大学高级语言程序设计课程</title>
<!--
静态页, 通过 Gitea 的 custom/public/assets/ 机制对外提供:
customization/custom/public/assets/tjhlp/ask-guide.html
-> {{AppSubUrl}}/assets/tjhlp/ask-guide.html
Gitea 只对 custom/public 下的 robots.txt、.well-known/ 和 assets/ 做静态服务。
本页不依赖 Gitea 的 JS/CSS, 可离线打开, 便于直接改文案。
-->
<style>
:root { color-scheme: light dark; }
body {
margin: 0 auto; padding: 2.5rem 1.25rem 4rem; max-width: 46rem;
font: 16px/1.75 -apple-system, "Segoe UI", "Noto Sans CJK SC", "Microsoft YaHei", sans-serif;
}
h1 { font-size: 1.75rem; margin-bottom: .25rem; }
h2 { font-size: 1.15rem; margin-top: 2.25rem; border-bottom: 1px solid #8884; padding-bottom: .35rem; }
code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: #888280; padding: .1em .35em; border-radius: 4px; }
.lead { color: #666; margin-top: 0; }
table { border-collapse: collapse; width: 100%; }
th, td { text-align: left; padding: .45rem .6rem; border-bottom: 1px solid #8883; vertical-align: top; }
.tip { border-left: 3px solid #3b82f6; background: #3b82f614; padding: .75rem 1rem; border-radius: 0 6px 6px 0; }
ol, ul { padding-left: 1.4rem; }
</style>
</head>
<body>
<h1>提问指南</h1>
<p class="lead">同济大学高级语言程序设计课程 · 课程答疑平台</p>
<div class="tip">
提问规范以课程官网的<a href="https://cpp.tongji.sh/Website/ask-question/">《学会提问》</a>为准,
本页是它在答疑平台里的速查版。遇到问题请先看
<a href="https://cpp.tongji.sh/Website/faq/">官网常见问题</a>与
<a href="https://cpp.tongji.sh/Website/">课程官网</a>上的作业说明。
</div>
<h2>提问前</h2>
<ol>
<li>在答疑仓库的 Issue 列表里用关键词(题号、函数名、报错信息)搜索,确认没有人问过。</li>
<li>自己先调试一遍:编译是否通过、报错信息是什么、最小复现是哪几行。</li>
<li>确认问题出在<strong>课程要求</strong>或<strong>你的代码</strong>,而不是环境没有按要求配置。</li>
</ol>
<h2>如何提问</h2>
<p>在对应仓库点击 <code>创建 Issue</code>,选择合适的模板后按模板填写:</p>
<ul>
<li><strong>题目信息</strong>:作业编号、题号、题目要求的关键点。</li>
<li><strong>相关代码</strong>:只贴必要片段,用代码块包裹,说明你期望的结果。</li>
<li><strong>实际现象</strong>:完整报错信息或错误输出(不要只截图,文字更便于检索)。</li>
<li><strong>已尝试的做法</strong>:查过什么资料、改过什么、结果如何。</li>
</ul>
<div class="tip">提问写得越具体,助教越容易直接定位问题;「我的代码不对,帮忙看看」这类问题通常只能得到「请补充信息」的回复。</div>
<h2>仓库与标签</h2>
<table>
<thead><tr><th>位置</th><th>用途</th></tr></thead>
<tbody>
<tr><td><code>general</code></td><td>课程内容、环境配置等一般性问题</td></tr>
<tr><td><code>hwNN</code></td><td>第 NN 次作业的特定问题</td></tr>
</tbody>
</table>
<p>助教会用标签标记处理状态,常见含义:</p>
<ul>
<li><strong>重复</strong>:已有同样的问题,请到原 Issue 继续讨论。</li>
<li><strong>待补充信息</strong>:描述不足以定位,请按提示补充。</li>
<li><strong>已解决</strong>:问题已答复,请确认后自行关闭。</li>
</ul>
<h2>其它</h2>
<ul>
<li>不要在 Issue 里粘贴完整的学号、密码等个人信息。</li>
<li>作业截止前是提问高峰,助教按时间顺序处理,请耐心等待。</li>
<li>与个人成绩、抄袭认定相关的事情请直接联系老师,不要发在公开 Issue 里。</li>
</ul>
<h2>相关站点</h2>
<ul>
<li><a href="https://cpp.tongji.sh/Website/">课程官网</a>:课程信息、作业说明、环境配置、扩展阅读。</li>
<li><a href="https://cpp.tongji.sh/Website/ask-question/">学会提问</a>:完整的提问规范,提问前请通读。</li>
<li><a href="https://cpp.tongji.sh/Website/faq/">常见问题</a>:中文乱码、Visual Studio 配置等高频问题。</li>
<li><a href="https://cpp.tongji.sh/Website/contact">联系我们</a>:网站问题与课程团队联系方式。</li>
</ul>
</body>
</html>
@@ -0,0 +1,193 @@
{{/*
导航栏, 整文件覆盖 Gitea 内置 templates/base/head_navbar.tmpl。
相对上游只改了两处: 未登录时的「帮助」和用户菜单里的「帮助」指向课程提问指南,
不再外链 docs.gitea.com。上游基线见 upstream/<版本>/templates/base/head_navbar.tmpl,
升级时请 diff 该基线后重新合并, 不要直接覆盖本文件。
*/}}
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
<div class="navbar-left">
<!-- the logo -->
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
</a>
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
<div class="ui secondary menu navbar-mobile-right only-mobile">
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
</div>
<!-- navbar links non-mobile -->
{{if and .IsSigned .MustChangePassword}}
{{/* No links */}}
{{else if .IsSigned}}
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
{{end}}
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
{{end}}
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
{{if .ShowMilestonesDashboardPage}}
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
{{end}}
{{end}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{else if .IsLandingPageOrganizations}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
{{else}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{end}}
{{template "custom/extra_links" .}}
{{if not .IsSigned}}
<a class="item" href="https://cpp.tongji.sh/Website/">课程官网</a>
<a class="item" href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html">提问指南</a>
{{end}}
</div>
<!-- the full dropdown menus -->
<div class="navbar-right">
{{if and .IsSigned .MustChangePassword}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else if .IsSigned}}
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
<span class="flex-text-block">
{{svg "octicon-plus"}}
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
</span>
<div class="menu">
<a class="item" href="{{AppSubUrl}}/repo/create">
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
</a>
{{if not .DisableMigrations}}
<a class="item" href="{{AppSubUrl}}/repo/migrate">
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
</a>
{{end}}
{{if .SignedUser.CanCreateOrganization}}
<a class="item" href="{{AppSubUrl}}/org/create">
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
</a>
{{end}}
</div><!-- end content create new menu -->
</div><!-- end dropdown menu create new -->
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text tw-flex tw-items-center">
<span class="navbar-avatar">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
</span>
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{.SignedUser.HomeLink}}">
{{svg "octicon-person"}}
{{ctx.Locale.Tr "your_profile"}}
</a>
{{if not .DisableStars}}
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
{{svg "octicon-star"}}
{{ctx.Locale.Tr "your_starred"}}
</a>
{{end}}
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
{{svg "octicon-bell"}}
{{ctx.Locale.Tr "notification.subscriptions"}}
</a>
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
{{svg "octicon-tools"}}
{{ctx.Locale.Tr "your_settings"}}
</a>
<a class="item" href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html">
{{svg "octicon-question"}}
提问指南
</a>
<a class="item" href="https://cpp.tongji.sh/Website/">
{{svg "octicon-book"}}
课程官网
</a>
{{if .IsAdmin}}
<div class="divider"></div>
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
{{svg "octicon-server"}}
{{ctx.Locale.Tr "admin_panel"}}
</a>
{{end}}
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else}}
{{if .ShowRegistrationButton}}
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
{{svg "octicon-person"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
</a>
{{end}}
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
{{svg "octicon-sign-in"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
</a>
{{end}}
</div><!-- end full right menu -->
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
{{if $activeStopwatch}}
<div class="active-stopwatch-popup tippy-target">
<div class="flex-text-block tw-p-3">
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
{{svg "octicon-issue-opened" 16}}
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
</a>
<div class="tw-flex tw-gap-1">
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
>{{svg "octicon-square-fill"}}</button>
</form>
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
>{{svg "octicon-trash"}}</button>
</form>
</div>
</div>
</div>
{{end}}
</nav>
{{template "base/head_banner"}}
+82
View File
@@ -0,0 +1,82 @@
{{/*
首页落地页, 整文件覆盖 Gitea 内置 templates/home.tmpl。
维护约定:
* 上游基线: customization/upstream/<版本>/templates/home.tmpl
升级 Gitea 时先 diff 基线, 把上游的结构性改动合并回来, 再重做文案。
* 文案直接写中文(平台只面向中文用户), 不复用 Gitea 的 startpage.* 文案,
这样首页不再出现「一款极易搭建的自托管 Git 服务」之类的自我推销。
* 只改文案/图标/链接, 保留原有 class 与结构, 避免升级后样式失效。
* 课程官网地址 https://cpp.tongji.sh/Website/ 在本文件、base/head_navbar.tmpl、
public/assets/tjhlp/ask-guide.html 以及 issue-templates 下两个 config.yaml 里
各出现一次, 换域名/路径时这几处要一起改(见 customization/README.md「与官网联动」)。
*/}}
{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
<div class="tw-mb-8 tw-px-8">
<div class="center">
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{AppName}}">
<div class="hero">
<h1 class="ui icon header title tw-text-balance">
{{AppName}}
</h1>
<h2 class="tw-text-balance">同济大学高级语言程序设计课程答疑平台</h2>
</div>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-search"}} 先搜索,再提问
</h1>
<p class="large tw-text-balance">
大部分问题同学已经问过。提问前请先在
<a href="{{AppSubUrl}}/explore/repos">课程答疑仓库</a>
的 Issue 列表里搜索关键词,避免重复提问。
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-checklist"}} 按模板提问
</h1>
<p class="large tw-text-balance">
新建 Issue 时请选择合适的模板,写清题号、相关代码、报错信息和已经尝试过的做法。
提问规范见课程官网<a href="https://cpp.tongji.sh/Website/ask-question/">《学会提问》</a>,
平台操作见<a href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html">提问指南</a>。
</p>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-repo"}} 浏览课程仓库
</h1>
<p class="large tw-text-balance">
一般性问题放在 <code>general</code> 仓库,各次作业的问题放在对应的 <code>hwNN</code> 仓库,
可在<a href="{{AppSubUrl}}/explore/repos">仓库列表</a>中查看。
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-comment-discussion"}} 助教在线答疑
</h1>
<p class="large tw-text-balance">
助教会通过 Issue 回复,并用标签标记重复、已解决、待补充信息等问题。
问题解决后请回复确认,便于我们归档。
</p>
</div>
</div>
<div class="ui center aligned basic segment tw-px-8">
<p class="large">
相关站点:
<a href="https://cpp.tongji.sh/Website/">课程官网</a> ·
<a href="https://cpp.tongji.sh/Website/ask-question/">学会提问</a> ·
<a href="https://cpp.tongji.sh/Website/faq/">常见问题</a> ·
<a href="https://cpp.tongji.sh/Website/contact">联系我们</a>
</p>
<p>
<small>本平台只用于课程答疑,课程通知、作业要求等以课程官网与课程群为准。</small>
</p>
</div>
</div>
{{template "base/footer" .}}
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
# 拉取指定 Gitea 版本的上游文件快照到 upstream/<版本>/。
#
# 快照是定制构建的基线: build.py 由它 + overrides/ 生成最终 locale;
# templates/ 下我们整文件覆盖的模板也以它为 diff 依据。
#
# 用法:
# customization/fetch-upstream.sh 1.27.3
#
# 只下载源码包并抽取 upstream-files.txt 列出的文件, 不会保存整份源码。
set -euo pipefail
VERSION="${1:?用法: fetch-upstream.sh <版本, 例如 1.27.3>}"
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DEST="${HERE}/upstream/${VERSION}"
URL="https://dl.gitea.com/gitea/${VERSION}/gitea-src-${VERSION}.tar.gz"
TMP="$(mktemp -d)"
trap 'rm -rf "${TMP}"' EXIT
echo "下载 ${URL}"
curl -fsSL -o "${TMP}/src.tar.gz" "${URL}"
mkdir -p "${DEST}"
while read -r path; do
[ -z "${path}" ] && continue
case "${path}" in \#*) continue ;; esac
if ! tar -xzf "${TMP}/src.tar.gz" -C "${TMP}" "gitea-src-${VERSION}/${path}" 2>/dev/null; then
echo "✗ 上游不存在该文件(版本里改名/删除了?): ${path}" >&2
exit 1
fi
mkdir -p "${DEST}/$(dirname "${path}")"
cp "${TMP}/gitea-src-${VERSION}/${path}" "${DEST}/${path}"
echo " ✓ ${path}"
done <"${HERE}/upstream-files.txt"
echo "✓ 快照已更新到 ${DEST}"
echo " 下一步: python3 customization/build.py, 然后 diff 上游模板改动"
+1
View File
@@ -0,0 +1 @@
1.27.3
+16
View File
@@ -0,0 +1,16 @@
{
"_comment": [
"精确覆盖: 键名必须存在于同版本上游 locale_zh-CN.json, 否则构建报错。",
"在 rules 之后应用, 因此这里写的内容一定是最终结果。",
"改动前请对照上游原文; 含占位符(如 %s / %[1]s / %d / <strong>%d</strong>)的条目必须保留占位符。"
],
"overrides": {
"repo.activity.active_issues_count_1": "共 <strong>%d</strong> 个 Issue",
"repo.activity.active_issues_count_n": "共 <strong>%d</strong> 个 Issue",
"repo.activity.title.issues_1": "%d 个 Issue",
"repo.activity.title.issues_n": "%d 个 Issue",
"repo.milestones.filter_sort.most_issues": "按 Issue 数量从多到少",
"repo.milestones.filter_sort.least_issues": "按 Issue 数量从少到多",
"admin.repos.issues": "Issue 数"
}
}
@@ -0,0 +1,14 @@
{
"_comment": [
"按顺序对所有 zh-CN 译文做字面替换的规则。",
"适合「全站统一术语」这类批量修改, 新增术语时在这里加一条即可。",
"替换按数组顺序依次执行; 需要精修的具体条目请放到 locale_zh-CN.json(精确覆盖优先于本文件)。"
],
"rules": [
{
"note": "Issue 不译为「工单」, 直接沿用英文",
"from": "工单",
"to": "Issue"
}
]
}
+96
View File
@@ -0,0 +1,96 @@
# =============================================================================
# TJHLP 定制预览实例(与生产完全隔离, 只绑定回环)
#
# 目的: 在不动生产容器/数据的前提下, 用【与生产相同版本】的官方镜像验证
# customization/custom 下的模板、文案、静态资源效果。
#
# 与生产(deploy/compose.yaml)的区别:
# * 项目名 gitea-preview, 容器名 gitea-preview, 端口 127.0.0.1:2081
# * 数据库用 sqlite(预览不需要 PostgreSQL)
# * 数据目录 preview/data(gitignore), 删除即重置
# * RUN_MODE=dev: 修改 custom/ 下的模板或语言文件后自动热加载, 无需重启
# * 把 customization/custom 只读挂载到容器的 GITEA_CUSTOM/custom
#
# 用法(见 preview.sh):
# ./preview.sh up 启动
# ./preview.sh logs 看日志
# ./preview.sh down 停止
# ./preview.sh reset 停止并清空预览数据
# =============================================================================
name: gitea-preview
services:
gitea:
image: docker.gitea.com/gitea:${GITEA_VERSION:-1.27.3}
container_name: gitea-preview
restart: unless-stopped
environment:
# 与宿主当前用户对齐, 让 ./data 的属主正确(见 preview.sh)
USER_UID: ${PREVIEW_UID:-1001}
USER_GID: ${PREVIEW_GID:-1001}
TZ: ${TZ:-Asia/Shanghai}
APP_NAME: 同济高程-答疑平台(预览)
# dev(默认): 语言文件改动自动热加载(实测), 模板报错也不致命 —— 改文案方便;
# prod: 与生产完全一致, 任何改动都要 ./preview.sh reload。
# 注意: 模板是启动时编译的, dev 下改模板同样要重启(官方文档也是这么说的)。
RUN_MODE: ${PREVIEW_RUN_MODE:-dev}
# --- 数据库: sqlite(预览专用) -------------------------------------
GITEA__database__DB_TYPE: sqlite3
GITEA__database__PATH: /data/gitea/gitea.db
# --- 服务地址 ------------------------------------------------------
GITEA__server__PROTOCOL: http
GITEA__server__DOMAIN: 127.0.0.1
GITEA__server__ROOT_URL: http://127.0.0.1:${PREVIEW_PORT:-2081}/
GITEA__server__HTTP_ADDR: 0.0.0.0
GITEA__server__HTTP_PORT: "3000"
GITEA__server__DISABLE_SSH: "true"
GITEA__server__LFS_START_SERVER: "true"
GITEA__server__OFFLINE_MODE: "false"
# --- 安全: 跳过安装向导; 密钥不在这里指定 -------------------------
# LFS_JWT_SECRET / INTERNAL_TOKEN / JWT_SECRET 留空时 Gitea 会自己生成
# 并写回 /data/gitea/conf/app.ini(可写), 重启后保持不变。
GITEA__security__INSTALL_LOCK: "true"
# --- 注册 / 登录 ---------------------------------------------------
GITEA__service__DISABLE_REGISTRATION: "false"
GITEA__service__ENABLE_CAPTCHA: "false"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
GITEA__mailer__ENABLED: "false"
# --- 站点元信息与页脚: 去掉 Gitea 自我推销 -------------------------
# 段名里的点要写成 _0X2E_ (Gitea 的 GITEA__section__KEY 编码规则)
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"
GITEA__log__MODE: console
GITEA__log__LEVEL: ${GITEA_LOG_LEVEL:-info}
volumes:
- ./data:/data
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
# /data/gitea/{templates,public,options}, 而不是 /data/gitea/custom
# (后者是源码/二进制安装时 WorkPath/custom 的习惯写法)。
# 分开挂三个子目录: 既只读覆盖定制内容, 又不遮住同级的 conf/、log/。
- ../custom/templates:/data/gitea/templates:ro
- ../custom/public:/data/gitea/public:ro
- ../custom/options:/data/gitea/options:ro
- /etc/localtime:/etc/localtime:ro
ports:
# 只绑定回环, 预览实例不对内网/外网暴露
- "127.0.0.1:${PREVIEW_PORT:-2081}:3000"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
interval: 10s
timeout: 5s
retries: 10
start_period: 60s
+136
View File
@@ -0,0 +1,136 @@
#!/usr/bin/env bash
# 预览实例管理脚本: 见 compose.yaml 顶部说明。
#
# ./preview.sh up 构建定制产物并启动预览 (http://127.0.0.1:2081)
# ./preview.sh down 停止预览(保留数据)
# ./preview.sh reset 停止并删除预览数据(下次全新安装)
# ./preview.sh logs 跟踪日志
# ./preview.sh ps 查看状态
# ./preview.sh shell 进入容器
# ./preview.sh admin 在预览实例里建一个管理员(用于验证登录后的页面)
# ./preview.sh check 构建校验 + 首页文案/页脚/元信息抽查
#
# 说明: 本机 docker 需要 docker 组权限; 当前 shell 没有时会自动改用
# `sg docker -c ...`(sg 读 /etc/group 的成员关系, 不需要 sudo)。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ROOT="$(cd "${HERE}/.." && pwd)"
COMPOSE_FILE="${HERE}/compose.yaml"
PORT="${PREVIEW_PORT:-2081}"
BASE_URL="http://127.0.0.1:${PORT}"
export PREVIEW_UID="$(id -u)"
export PREVIEW_GID="$(id -g)"
# 是否需要套 sg docker
if docker info >/dev/null 2>&1; then
compose() { docker compose -f "${COMPOSE_FILE}" "$@"; }
elif command -v sg >/dev/null 2>&1 && sg docker -c 'docker info' >/dev/null 2>&1; then
compose() { sg docker -c "docker compose -f '${COMPOSE_FILE}' $*"; }
else
echo "✗ 当前用户没有 docker 权限(既不能直连, 也不能通过 docker 组)" >&2
exit 1
fi
prepare() {
# 生成定制产物(语言文件等)
python3 "${ROOT}/build.py" --quiet
# 预建数据目录: 属主等于当前用户, 容器 entrypoint 就不会对只读挂载做 chown。
# .ssh 必须由我们建: 否则容器以 root 建出 0700 目录, 降权后的 gitea 进程
# 写不了 authorized_keys。
mkdir -p "${HERE}/data/gitea/conf" "${HERE}/data/git/.ssh" "${HERE}/data/ssh"
chmod 700 "${HERE}/data/git/.ssh"
}
case "${1:-}" in
up)
prepare
compose up -d
echo "预览地址: ${BASE_URL} (数据目录: ${HERE}/data)"
echo "首次启动约需 10~30 秒; 用 ./preview.sh logs 观察进度"
;;
down)
compose down
;;
reload)
# 模板改完必须重启才生效(prod/dev 都一样); 语言文件在 dev 下会自动热加载
python3 "${ROOT}/build.py" --quiet
compose restart gitea
echo "已重启, 预览地址: ${BASE_URL}"
;;
reset)
compose down
if ! rm -rf "${HERE}/data" 2>/dev/null; then
# 容器可能以 root 身份建过 data/git/.ssh(0700), 宿主用户删不掉;
# 用一次性 root 容器清掉再删(正常流程不会走到这里, 见 prepare 的说明)。
compose run --rm -T --user 0 --entrypoint /bin/sh gitea -c 'rm -rf /data/git /data/ssh' >/dev/null
rm -rf "${HERE}/data"
fi
echo "已清空预览数据"
;;
logs)
compose logs -f --tail=100
;;
ps)
compose ps
;;
shell)
compose exec gitea bash
;;
admin)
USERNAME="${2:-previewadmin}"
PASSWORD="${3:-previewadmin123}"
# -u git: gitea 命令拒绝以 root 运行
compose exec -T -u git gitea gitea admin user create \
--username "${USERNAME}" --password "${PASSWORD}" \
--email "${USERNAME}@example.com" --admin --must-change-password=false
echo "管理员: ${USERNAME} / ${PASSWORD}"
;;
check)
python3 "${ROOT}/build.py" --check --quiet
fail=0
ok() { echo "✓ $1"; }
bad() {
echo "✗ $1"
fail=1
}
html="$(mktemp)"
trap 'rm -f "${html}"' EXIT
curl -fsS "${BASE_URL}/" -o "${html}"
grep -q "先搜索,再提问" "${html}" && ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
grep -q "assets/tjhlp/ask-guide.html" "${html}" && ok "导航栏/首页已指向课程提问指南" || bad "没找到提问指南链接"
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${html}" &&
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
! grep -qi "powered by" "${html}" && ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
! grep -q "docs.gitea.com" "${html}" && ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${html}" &&
ok "meta description 已替换" || bad "meta description 未替换"
curl -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" &&
ok "custom/public 静态页可访问" || bad "提问指南静态页 404"
# --- 与课程官网的联动 -------------------------------------------------
grep -q "https://cpp.tongji.sh/Website/" "${html}" &&
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
grep -q "https://cpp.tongji.sh/Website/ask-question/" "${html}" &&
ok "首页已链接官网《学会提问》" || bad "首页没有《学会提问》链接"
guide="$(mktemp)"
curl -fsS "${BASE_URL}/assets/tjhlp/ask-guide.html" -o "${guide}"
grep -q "Website/ask-question/" "${guide}" && ok "站内提问指南已回链官网" || bad "站内提问指南没有官网链接"
rm -f "${guide}"
! grep -rq "example.com" "${ROOT}/../issue-templates/" &&
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" &&
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
[ "${fail}" = 0 ] && echo "全部检查通过" || echo "存在检查未通过项"
exit "${fail}"
;;
*)
sed -n '2,18p' "$0"
exit 1
;;
esac
+9
View File
@@ -0,0 +1,9 @@
# 需要留快照的上游文件(相对 gitea 源码根目录), 每行一个, # 开头为注释。
#
# 什么时候往这里加一行:
# * build.py 生成的 locale 基线(必须)
# * custom/templates/ 下我们整文件覆盖的内置模板(必须, 否则升级时没有 diff 依据)
# * custom/options/ 下我们覆盖的内置数据文件(如 gitignore/label)
options/locale/locale_zh-CN.json
templates/home.tmpl
templates/base/head_navbar.tmpl
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,182 @@
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
<div class="navbar-left">
<!-- the logo -->
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
</a>
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
<div class="ui secondary menu navbar-mobile-right only-mobile">
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
</div>
<!-- navbar links non-mobile -->
{{if and .IsSigned .MustChangePassword}}
{{/* No links */}}
{{else if .IsSigned}}
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
{{end}}
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
{{end}}
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
{{if .ShowMilestonesDashboardPage}}
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
{{end}}
{{end}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{else if .IsLandingPageOrganizations}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
{{else}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{end}}
{{template "custom/extra_links" .}}
{{if not .IsSigned}}
<a class="item" target="_blank" href="https://docs.gitea.com">{{ctx.Locale.Tr "help"}}</a>
{{end}}
</div>
<!-- the full dropdown menus -->
<div class="navbar-right">
{{if and .IsSigned .MustChangePassword}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else if .IsSigned}}
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
<span class="flex-text-block">
{{svg "octicon-plus"}}
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
</span>
<div class="menu">
<a class="item" href="{{AppSubUrl}}/repo/create">
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
</a>
{{if not .DisableMigrations}}
<a class="item" href="{{AppSubUrl}}/repo/migrate">
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
</a>
{{end}}
{{if .SignedUser.CanCreateOrganization}}
<a class="item" href="{{AppSubUrl}}/org/create">
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
</a>
{{end}}
</div><!-- end content create new menu -->
</div><!-- end dropdown menu create new -->
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text tw-flex tw-items-center">
<span class="navbar-avatar">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
</span>
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{.SignedUser.HomeLink}}">
{{svg "octicon-person"}}
{{ctx.Locale.Tr "your_profile"}}
</a>
{{if not .DisableStars}}
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
{{svg "octicon-star"}}
{{ctx.Locale.Tr "your_starred"}}
</a>
{{end}}
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
{{svg "octicon-bell"}}
{{ctx.Locale.Tr "notification.subscriptions"}}
</a>
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
{{svg "octicon-tools"}}
{{ctx.Locale.Tr "your_settings"}}
</a>
<a class="item" target="_blank" href="https://docs.gitea.com">
{{svg "octicon-question"}}
{{ctx.Locale.Tr "help"}}
</a>
{{if .IsAdmin}}
<div class="divider"></div>
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
{{svg "octicon-server"}}
{{ctx.Locale.Tr "admin_panel"}}
</a>
{{end}}
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else}}
{{if .ShowRegistrationButton}}
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
{{svg "octicon-person"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
</a>
{{end}}
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
{{svg "octicon-sign-in"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
</a>
{{end}}
</div><!-- end full right menu -->
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
{{if $activeStopwatch}}
<div class="active-stopwatch-popup tippy-target">
<div class="flex-text-block tw-p-3">
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
{{svg "octicon-issue-opened" 16}}
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
</a>
<div class="tw-flex tw-gap-1">
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
>{{svg "octicon-square-fill"}}</button>
</form>
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
>{{svg "octicon-trash"}}</button>
</form>
</div>
</div>
</div>
{{end}}
</nav>
{{template "base/head_banner"}}
@@ -0,0 +1,51 @@
{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
<div class="tw-mb-8 tw-px-8">
<div class="center">
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}">
<div class="hero">
<h1 class="ui icon header title tw-text-balance">
{{AppName}}
</h1>
<h2 class="tw-text-balance">{{ctx.Locale.Tr "startpage.app_desc"}}</h2>
</div>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-flame"}} {{ctx.Locale.Tr "startpage.install"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.install_desc" "https://docs.gitea.com/installation/install-from-binary" "https://github.com/go-gitea/gitea/tree/master/docker" "https://docs.gitea.com/installation/install-from-package"}}
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-device-desktop"}} {{ctx.Locale.Tr "startpage.platform"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.platform_desc" "https://go.dev/"}}
</p>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-rocket"}} {{ctx.Locale.Tr "startpage.lightweight"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.lightweight_desc"}}
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-code"}} {{ctx.Locale.Tr "startpage.license"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.license_desc" "https://gitea.dev" "gitea.dev" "https://github.com/go-gitea/gitea"}}
</p>
</div>
</div>
</div>
{{template "base/footer" .}}
+181
View File
@@ -0,0 +1,181 @@
# 官网 ↔ 答疑平台 联动方案(提案)
> 这份文档是**给 Website 仓库的改动提案**, 不涉及本仓库代码。
> 平台侧的入口已经落地(见 `README.md` 「4.2 与课程官网联动」), 本文只讲官网侧怎么接。
## 0. 事实与现状(已核实)
| 项 | 事实 |
| ---- | ---- |
| 官网仓库 | `https://github.com/Tongji-High-level-Language-Programming/Website.git`(`/home/ymy/tjhlp-website`) |
| 站点框架 | VitePress, `base: "/Website/"`, 构建命令 `pnpm docs:build` |
| 线上地址 | `https://cpp.tongji.sh/Website/`(Apache `DocumentRoot=/home/httpd/hlp-website`, `RedirectMatch ^/$ /Website/`) |
| 部署方式 | GitHub Actions: push 到 `main` → 构建 → 同时发 GitHub Pages 与该服务器(`rsync` 到 `/home/httpd/hlp-website/Website/`) |
| 答疑平台 | `https://cpp.tongji.sh/QA/`(同一台机器, Apache `ProxyPass /QA`) |
| 图片资产 | Git LFS(`.gitattributes`), 15 张 PR 截图都是 LFS 指针 |
| 现状 main | 已到 PR #54; `#52` 的分支 `oierxjn:docs/gitea-tut` 落后 5 个提交, 但可干净合并 |
**关于 base 的坑(已实测)**: VitePress 会给 Markdown 里以 `/` 开头的站内链接自动加上
`base`。部署产物里 `docs/ask-question/index.md` 的 `[本站 FAQ 页面](/faq/)` 生成的是
`href="/Website/faq/"`。所以**跨站链接不能写 `/QA/`**(会被改写成 `/Website/QA/`),
必须写完整 URL —— PR #52 里写完整 URL 是对的。
## 1. PR #52 现状
标题: *WIP: docs: Update Gitea tutorial and contact information with new references*(draft),
作者 `oierxjn`, 分支 `docs/gitea-tut`, 18 个文件 `+167 -1`:
- `docs/faq/gitea/index.md` + 15 张截图: 平台使用指南(登录、搜索、创建/关闭 Issue)
- `docs/.vitepress/config.mts`: 「常见问题」导航加下拉项「高程答疑平台」
- `docs/ask-question/index.md`: 正文加入平台入口
- `docs/contact.md`: 「QQ 群提问」→「答疑平台提问」
方向正确, 下面是可以补齐/修正的点。
## 2. 复查发现的问题
### P1 · 建议修掉
1. **`docs/faq/gitea/index.md` 没有文件末尾换行**(`\ No newline at end of file`)。
仓库有 prettier + lint-staged, 建议补上, 避免后续 diff 噪音。
2. **同页第一段主语写错**:「课程的答疑主要在…进行。**网站**仅限同济大学校园网或同济 VPN
访问。」—— 上一句主语是平台。建议改为「平台与本站均仅限校园网 / 同济 VPN 访问」。
3. **同页 `/contact.md` 链接**:`[联系团队](/contact.md)`。虽然 VitePress 能处理 `.md`
链接, 但站内其他地方(导航、侧栏)统一写 `/contact`, 建议一致; 该句还缺句号。
4. **旧组织名**:`docs/contact.md`(PR 改动行)与 `docs/.vitepress/config.mts` 的
`socialLinks` 都写成 `Tongji-High-level-Programming-Language`(词序颠倒)。实测该
地址目前 200 是因为 GitHub 的组织改名重定向, 建议改成当前组织名
`Tongji-High-level-Language-Programming`, 不要依赖重定向。
### P2 · 建议调整
5. **入口层级偏低**:目前只有「常见问题」下拉里的一个子项。建议在**顶部导航**加一个
一级「答疑平台」外链, 并在**首页 hero** 加一个 `答疑平台` 按钮 —— 这是学生最需要的入口。
6. **首页提示过期**:`docs/index.md` 底部 `::: danger` 写着「所有通知、作业等重要信息请以
官方课程 QQ 群为准」。既然答疑已迁到平台, 建议改为「以课程官网与答疑平台公告为准」,
并把 `学会提问`/`FAQ` 之外补上平台入口。
7. **`docs/faq/index.md` 没有平台入口**:FAQ 是学生最常翻的页面, 建议在顶部 tip 里直接
给出平台链接与《使用指南》。
8. **「为什么 Gitea 作为答疑平台?」整段引用了 Gitea 官方宣传文案**, 其中包含「极易安装…
自建 Git 服务」这种推销语, 与网站正文风格不符。建议只保留后半段「如你所见, Gitea 提供了
完整的 Issue 管理功能…」。
9. **账号开通方式待确认**:同页写「账号目前由管理员统一开通, 没有额外的注册入口」。如果
实际是统一身份认证(OIDC)首次登录自动建号, 这句会误导学生 —— 需要按实际流程改写。
### P3 · 后续
10. **截图会随定制上线而部分过期**:15 张截图拍摄于平台定制之前, 其中 `MainPage.png` 是
Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑
平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样
流程重拍、**文件名不变**地替换, 这样正文不用改。
11. **内容重复**:官网《学会提问》与平台内 `/assets/tjhlp/ask-guide.html` 有重叠。平台侧
已把官网定为权威版本(站内页顶部注明"以官网为准"并给出链接), 官网页不必反向复制平台
操作细节, 链接到 `/faq/gitea/` 即可。
## 3. 建议改动(可直接套用)
### 3.1 `docs/.vitepress/config.mts`
```ts
// 答疑平台(校内 Apache 反代 /QA)。外链必须写完整 URL:
// VitePress 会给以 / 开头的站内链接加上 base(/Website/), 写 /QA/ 会变成 /Website/QA/。
const QA_URL = "https://cpp.tongji.sh/QA/";
// themeConfig.nav —— 在「首页」之后插入一级入口
{ text: "答疑平台", link: QA_URL },
// 「常见问题」下拉保留(PR #52 已加)
{
text: "常见问题",
link: "/faq/",
items: [{ text: "答疑平台使用指南", link: "/faq/gitea/" }],
},
// themeConfig.sidebar —— 「学会提问」之后加一条(侧栏支持外链)
{ text: "答疑平台", link: QA_URL },
// socialLinks —— 顺手改成当前组织名
link: "https://github.com/Tongji-High-level-Language-Programming/Website",
```
### 3.2 `docs/index.md`
```yaml
actions:
- theme: brand
text: 课程信息
link: /syllabus/
- theme: brand
text: 答疑平台 # 新增
link: https://cpp.tongji.sh/QA/
- theme: alt
text: 学会提问
link: /ask-question/
- theme: alt
text: FAQ
link: /faq/
```
```md
::: danger 注意
本网站目前仍处于试运行状态,可能存在内容的缺失、错误或更新不及时。所有通知、作业等重要信息
请以课程官网与答疑平台的公告为准,课程群内也会同步。
:::
```
### 3.3 `docs/faq/index.md`
```md
::: tip
提问前请务必认真阅读 [学会提问](/ask-question/) 一文。课程答疑在
[高程答疑平台](https://cpp.tongji.sh/QA/) 上进行,使用方式见 [答疑平台使用指南](/faq/gitea/)。
:::
```
### 3.4 `docs/contact.md`
```md
本校同学的课程相关问题,请在 [高程答疑平台](https://cpp.tongji.sh/QA/) 提问
([使用指南](/faq/gitea/))
对本网站的意见与建议,可以直接提交
[GitHub Issue](https://github.com/Tongji-High-level-Language-Programming/Website/issues)
或者联系课程团队:
```
### 3.5 `docs/faq/gitea/index.md`
- 第一段:「平台与本站均仅限同济大学校园网或同济 VPN 访问。」
- `[联系团队](/contact.md)` → `[联系团队](/contact)`。
- 文末补一个换行。
- 「为什么 Gitea 作为答疑平台?」删掉官方宣传语的引用块, 保留后半段说明。
- 如按 §3.1 在导航加了入口, 页内可直接用 `[答疑平台](https://cpp.tongji.sh/QA/)`。
## 4. 落地与验证
```bash
cd ~/tjhlp-website
git lfs install # 截图是 LFS 对象, 缺了会构建出坏图
pnpm install
pnpm docs:dev # 本地预览: http://localhost:5173/Website/
pnpm docs:build # 站内死链会在构建期报错, 作为校验
```
- PR #52 的分支落后 main 5 个提交(可干净合并), 建议 `git rebase origin/main` 后继续,
或直接基于最新 main 重建分支; **截图是 LFS 对象, 不要用 patch 传递, 要用分支/PR 传**。
- 合并到 `main` 后由 GitHub Actions 自动 rsync 到 `/home/httpd/hlp-website/Website/`,
无需手工部署; 部署后可用 `curl -s https://cpp.tongji.sh/Website/ | grep 答疑平台` 抽查。
- 平台侧的对应入口已就绪(导航栏「课程官网」、首页「相关站点」、Issue 模板
`contact_links`), 两边合并后建议用 `customization/preview/preview.sh check` 复查。
## 5. 待确认
1. 平台对外地址长期是否就是 `https://cpp.tongji.sh/QA/`?若有域名计划, 建议官网只维护一个
常量(如上面的 `QA_URL`)。
2. 账号开通方式(管理员统一开通 / OIDC 首次登录自动注册)——决定 FAQ 里那句话怎么写。
3. 「为什么 Gitea 作为答疑平台?」是保留精简版还是整段删除。
4. 截图重拍的时间点(建议在平台定制部署上线后)。