# 官网 ↔ 答疑平台 联动方案(提案) > 这份文档是**给 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` | | 线上地址 | `http://10.80.42.185/Website/`(Apache `DocumentRoot=/home/httpd/hlp-website`, `RedirectMatch ^/$ /Website/`) | | 部署方式 | GitHub Actions: push 到 `main` → 构建 → 同时发 GitHub Pages 与该服务器(`rsync` 到 `/home/httpd/hlp-website/Website/`) | | 答疑平台 | `http://10.80.42.185/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 = "http://10.80.42.185/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: http://10.80.42.185/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/) 一文。课程答疑在 [高程答疑平台](http://10.80.42.185/QA/) 上进行,使用方式见 [答疑平台使用指南](/faq/gitea/)。 ::: ``` ### 3.4 `docs/contact.md` ```md 本校同学的课程相关问题,请在 [高程答疑平台](http://10.80.42.185/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 在导航加了入口, 页内可直接用 `[答疑平台](http://10.80.42.185/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 http://10.80.42.185/Website/ | grep 答疑平台` 抽查。 - 平台侧的对应入口已就绪(导航栏「课程官网」、首页「相关站点」、Issue 模板 `contact_links`), 两边合并后建议用 `customization/preview/preview.sh check` 复查。 ## 5. 待确认 1. 平台对外地址长期是否就是 `http://10.80.42.185/QA/`?若有域名计划, 建议官网只维护一个 常量(如上面的 `QA_URL`)。 2. 账号开通方式(管理员统一开通 / OIDC 首次登录自动注册)——决定 FAQ 里那句话怎么写。 3. 「为什么 Gitea 作为答疑平台?」是保留精简版还是整段删除。 4. 截图重拍的时间点(建议在平台定制部署上线后)。