Files
tjhlp-gitea/customization/website-linkage.md
T
admin 1272c1ebec
deploy / deploy (push) Failing after 6s
fix: 引导链接统一指向官网提问指南(/Website/qa/ask/), 删掉平台内副本
官网改版后提问指南在 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 个测试全过。
2026-09-22 22:39:05 +08:00

9.1 KiB
Raw Blame History

官网 ↔ 答疑平台 联动方案(提案)

这份文档是给 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 · 建议调整

  1. 入口层级偏低:目前只有「常见问题」下拉里的一个子项。建议在顶部导航加一个 一级「答疑平台」外链, 并在首页 hero 加一个 答疑平台 按钮 —— 这是学生最需要的入口。
  2. 首页提示过期:docs/index.md 底部 ::: danger 写着「所有通知、作业等重要信息请以 官方课程 QQ 群为准」。既然答疑已迁到平台, 建议改为「以课程官网与答疑平台公告为准」, 并把 学会提问/FAQ 之外补上平台入口。
  3. docs/faq/index.md 没有平台入口:FAQ 是学生最常翻的页面, 建议在顶部 tip 里直接 给出平台链接与《使用指南》。
  4. 「为什么 Gitea 作为答疑平台?」整段引用了 Gitea 官方宣传文案, 其中包含「极易安装… 自建 Git 服务」这种推销语, 与网站正文风格不符。建议只保留后半段「如你所见, Gitea 提供了 完整的 Issue 管理功能…」。
  5. 账号开通方式待确认:同页写「账号目前由管理员统一开通, 没有额外的注册入口」。如果 实际是统一身份认证(OIDC)首次登录自动建号, 这句会误导学生 —— 需要按实际流程改写。

P3 · 后续

  1. 截图会随定制上线而部分过期:15 张截图拍摄于平台定制之前, 其中 MainPage.png 是 Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑 平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样 流程重拍、文件名不变地替换, 这样正文不用改。
  2. 内容重复(已在平台侧处理完):官网提问指南与平台内的副本曾有重叠。2026-09 起 提问指南只在官网保留一份(/Website/qa/ask/), 平台内的 /assets/tjhlp/ask-guide.html 已删除, 平台页面与 Issue 模板的引导链接全部指向官网; 官网页因此不必再考虑与平台副本同步的问题。

2026-09 官网改版后的路径:提问指南 /Website/qa/ask/、常见问题 /Website/qa/faq/、 联系我们 /Website/contact.html。旧的 /Website/ask-question/、/Website/faq/ 已变成 跳转页, /Website/contact 已经 404。本文下面几节写于改版前, 里面的 /ask-question/、/contact.md 等路径按新路径理解(PR #52 也要相应更新)。

3. 建议改动(可直接套用)

3.1 docs/.vitepress/config.mts

// 答疑平台(校内 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

  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/
::: danger 注意

本网站目前仍处于试运行状态,可能存在内容的缺失、错误或更新不及时。所有通知、作业等重要信息
请以课程官网与答疑平台的公告为准,课程群内也会同步。

:::

3.3 docs/faq/index.md

::: tip

提问前请务必认真阅读 [学会提问](/ask-question/) 一文。课程答疑在
[高程答疑平台](https://cpp.tongji.sh/QA/) 上进行,使用方式见 [答疑平台使用指南](/faq/gitea/)。

:::

3.4 docs/contact.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. 落地与验证

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. 截图重拍的时间点(建议在平台定制部署上线后)。