Files
tjhlp-gitea/customization/website-linkage.md
T
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

182 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 官网 ↔ 答疑平台 联动方案(提案)
> 这份文档是**给 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. 截图重拍的时间点(建议在平台定制部署上线后)。