Compare commits

..
17 Commits
Author SHA256 Message Date
admin 9446850182 feat: Issue 发布者/回答者显示姓名, 而不是学号
deploy / deploy (push) Successful in 25s
Issue 页的作者名走 User.GetDisplayName(), 默认返回 login(学号),
看不到老师/助教认得的姓名。打开站点级开关 [ui] DEFAULT_SHOW_FULL_NAME
后改为显示 full_name, 未填姓名的用户回退学号。

配合 OIDC 侧把 full_name 覆盖成 display_name(学号-姓名), 即可同时
显示学号与姓名; 存量用户需重新登录才会刷新, 见 scripts/README.md。

- deploy/compose.yaml: GITEA__ui__DEFAULT_SHOW_FULL_NAME=true
- customization/preview/compose.yaml: 同步, 便于预览验证
- customization/README.md: 配置表 / 环境变量片段 / 已验证清单
- scripts/settings.toml: CLI 调 API 的地址改为宿主回环 127.0.0.1:2080
  (10.80.42.185:3000 未对外开放, 上层反代返回 502)

已在预览实例(Gitea 1.27.3)验证: 「由 X 创建」与正文/评论作者
均显示 full_name。
2026-09-25 19:04:24 +08:00
admin 8d5c8c6bae docs(deploy): 把「SSH 默认关闭」的说明对齐实测, 并补上启用步骤
起因是加公钥时页面提示"SSH 目前已禁用, 这些密钥仅用于提交签名验证"。查证后修正两处
过时/失效的说明:

- compose 里那行注释让读者去看 deploy/README.md「启用 SSH 克隆」—— 该小节并不存在
- README 兼容性表里 server.DISABLE_SSH 的理由写的是"实测 /home/git/.ssh 不存在"。
  实测(2026-09-23): 容器里 git 用户家目录是 /data/git, /data/git/.ssh/authorized_keys
  存在且由 Gitea 维护(形如 command="… gitea serv key-N"), 加过公钥的账号启用后即可用

新增「如需启用 SSH 克隆(可选, 默认关闭)」小节, 记下查证到的事实: 镜像自带 sshd(s6 服务
openssh, 容器内已在 0.0.0.0:22 监听, 只是没发布端口)、host key 在持久卷 /data/ssh、
sshd_config 只允许 git 用户公钥认证(PasswordAuthentication no / AllowUsers git /
PermitRootLogin no / 不转发)、宿主 22 被宿主自己的 sshd 占用; 以及要同时改的三处
(DISABLE_SSH / SSH_DOMAIN / SSH_PORT + 发布 2222:22)、验证命令和利弊。
2026-09-23 02:08:49 +08:00
admin 53116f7a23 fix(ci): 部署时必须重启 gitea —— 指纹要与上次成功部署比, 而不是 build.py 前后
deploy / deploy (push) Successful in 11s
事故经过(2026-09-22): 「提问指南」换地址那个提交推送后 CI 挂了, auto-deploy 回滚。
check.sh 报「没找到官网提问指南链接 / 仍有旧地址」—— 但脚本确实把部署克隆同步到了新
提交、语言文件也重新生成了。原来 deploy() 比较的是 build.py 运行【前后】的指纹: 那只能
发现语言文件被重新生成, 纯模板改动前后完全一样 → 从不重启 → 容器继续用启动时加载的旧
模板 → 断言失败 → 整个部署被判失败并回滚。也就是说: 任何只改模板的提交都必然挂 CI。

修法: 把指纹记在 deploy/.state/custom-hash 里, 与【上次成功部署】的指纹比较, 不同就
restart gitea(restart 而不是 up -d: compose 配置没变时 up -d 不重建容器)。rollback 路径
改成 deploy force 无条件重启 —— 失败的那次可能已经用新模板重启过容器, 回滚必须再重启
回去, 顺便也修好下面这个副作用。

顺带修一个 bind mount 的坑: 挂载【源目录】被「删掉再建」后容器里挂的还是旧 inode(空
目录)。这次事故里 public/ 下的文件被删光、git 顺手删掉空目录, 于是线上
/QA/assets/tjhlp/ask-guide.html 变成 404。已在预览上复现([B] 404 → restart 后 [C] 200),
restart 会重新解析挂载, 所以上面的修法同时把它修好。

验证(不碰生产的沙箱, 假 docker + 桩 verify/check):
  1 全新状态首次部署        → up -d + restart ✓
  2 什么都没改再部署        → 不重启 ✓
  3 只改一个模板文件        → 重启 ✓(这次的回归点)
  4 之后再来一次            → 不重启 ✓
  5 check 失败 → 回滚       → checkout PREV + 强制 restart ✓, 状态文件不被污染 ✓
另外 check.sh / preview.sh 的失败信息里加了「模板改动要重启才生效」的提示, 并把
ci-cd.md §5.2(脚本清单+为什么必须 restart)与 README §12 速查表同步更新。
2026-09-23 01:52:58 +08:00
admin 1272c1ebec fix: 引导链接统一指向官网提问指南(/Website/qa/ask/), 删掉平台内副本
deploy / deploy (push) Failing after 6s
官网改版后提问指南在 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
admin 487c9e8726 fix(ci): check.sh 的覆盖层路径写错(断言被静默跳过); 并断言首页卡片模板
`ROOT` 是仓库根, 但断言用的是 `${ROOT}/custom/...`, 那个路径根本不存在, 于是
`if [[ -f ... ]]` 永远为假 —— 「生成的 zh-CN 语言文件已无工单」这条从未真正跑过
(在预览/生产上跑都是直接跳过, 看不出来)。改成 `customization/custom/...`。

顺带加上首页(登录后)学期答疑入口卡片的模板层断言: 卡片模板在位 + dashboard.tmpl
里确实 include 了它。渲染结果需要登录才能看, 那部分在 preview.sh check 里
(它用 previewadmin 登录后抓首页)。

实测: customization/check.sh 对预览与生产都跑通(生产多一条 OIDC 入口 307)。
2026-09-22 22:22:56 +08:00
admin 787481c2c8 feat: 首页(登录后)顶部加「本学期答疑入口」大卡片
登录后首页原本是贡献热力图/最近活动/仓库列表, 对只来提问的同学是干扰。
现在 navbar 之下、热力图之上插一张约 1/3 屏高(33vh)的卡片, 里面一个按钮直达
本学期答疑区, 顺带给出「提问指南」和官网《学会提问》的入口。

实现:
- custom/templates/user/dashboard/dashboard.tmpl: 覆盖上游同名模板,
  只比上游多一行 {{template "custom/tjhlp_semester_card" .}}(便于升级时 diff)
- custom/templates/custom/tjhlp_semester_card.tmpl: 卡片本体(自己写的), 规则:
    * 数据来自 .Orgs(当前用户所属组织)
    * 学期组织 = 名字形如 tjhlp-<5 位数字>; 26271 => 26|27|1 => 2026-2027 学年第一学期
      旧命名 tjhlp-2026s(带字母)、course-team 之类都不认
    * 同时匹配多个取最新(名字最大), 按钮指向 <学期组织>/general/issues
    * 一个都不匹配 => 整张卡片不显示
  判定/文案都在这个文件里, 不依赖 Tailwind 工具类(用行内样式), 升级影响面最小

预览侧:
- preview.sh 新增 semester: 造学期组织 + general 仓库(幂等), 用于看卡片
- preview.sh check 增加登录后的断言(卡片存在 / 按钮链接 / 33vh), 现 17 项全过
  预览里实测三个用户: previewadmin(在 26271/25261/2026s 三个组织里) -> 26271,
  student1(只在 27282) -> 27282, student2(无组织) -> 不显示卡片且页面正常
2026-09-22 22:21:18 +08:00
admin 7ff17f8b2a fix(ci): 收窄 runner 的宿主能力 —— 由 deploy job 自己申报挂载
deploy / deploy (push) Successful in 4s
原来 runner 用 container.options 把 docker.sock / 部署克隆 / 裸库 / docker CLI
全局挂给【每个】job。这个 runner 上的任何 workflow(以后加的 PR 检查、测试)都因此
白拿 docker = root 等价能力。

改成:
  * container.docker_host: "-"  → 不再自动把 socket 挂进 job 容器
  * 删掉全局 container.options 挂载
  * 五项挂载(socket/部署克隆/裸库/docker CLI/compose 插件)由 deploy job 在 workflow
    的 container.volumes 里自己申报
  * 五项仍列在 container.valid_volumes 白名单里(不在表里的申报会被静默丢弃)

效果: 不申报的 job 默认是裸容器(实测看不到 /home/ymy/deploy 与 /srv/gitea)。

验证边界(诚实记录):
  * Gitea 侧确认会把整个 job 的 YAML(含 container:)作为任务载荷发给 runner
    —— services/actions/run.go 里 payload, _ := v.Marshal()
  * act 侧确认会采纳 job 申报的 volumes —— act_runner exec 实测
  * 但 `act_runner exec` 有自己的 --container-daemon-socket 默认值、也不读配置里的
    valid_volumes/docker_host, 所以这两项只能靠一次真实运行确认; 失败模式是
    "第一步 cd 就报错、线上不受影响"
2026-09-22 20:12:57 +08:00
admin 99547005bd fix(ci): cd into the deploy clone before running auto-deploy.sh
deploy / deploy (push) Successful in 4s
The workflow has no actions/checkout, so the default workdir is empty and
'./deploy/scripts/auto-deploy.sh' was not found (exit 127).
2026-09-21 23:49:35 +08:00
admin 438c0f4e01 fix(ci): mount the bare repo for the deploy clone's local remote
deploy / deploy (push) Failing after 7s
The deploy clone fetches from /srv/gitea/git/repositories/... which the job
container cannot see, so 'git fetch' failed with exit 128. Mount it read-only
and whitelist it.
2026-09-21 23:47:45 +08:00
admin c5fdbe16d6 fix(ci): whitelist deploy bind mounts in runner valid_volumes
deploy / deploy (push) Failing after 2s
act_runner drops any volume not listed in container.valid_volumes, so the
options --volume flags for the deploy clone and docker CLI were ignored and
the job failed at 'cd /home/ymy/deploy/tjhlp-gitea'.
2026-09-21 23:45:53 +08:00
admin 77b9e72388 fix(oauth2): request the email scope from the OIDC provider
deploy / deploy (push) Failing after 2s
Gitea maps the standard email claim during auto-registration, but the
provider only returns email when the email scope is requested. Adding it
here (the IdP also now allows the email scope for the tjhlp-gitea client)
fixes 'OAuth2 提供商返回缺失的字段: email'.
2026-09-21 23:14:51 +08:00
admin 73ce8162aa feat(ci): 落地 main 自动部署的可复用件(runner 配置/部署脚本/定制断言/工作流)
deploy / deploy (push) Skipped
按 deploy/ci-cd.md 方案把除推送触发之外的东西都准备好:

- customization/check.sh <base-url>: 把 preview.sh check 里的"定制生效"断言抽成
  任意实例可跑的脚本(首页/页脚/meta/官网链接/登录页两张卡/无通行密钥方框/
  无「工单」/无 example.com), 另加生产才有的 OIDC 入口 307 断言(404 = 认证源没注册上)。
  实测对生产 17/17 通过。
- deploy/scripts/auto-deploy.sh: build.py -> compose up -d -> verify.sh + check.sh,
  失败自动回滚到 deploy/.state/last-deployed; flock 串行; 结束时把 clone 所有权还给
  ymy(job 容器里是 root); 内网验证强制不走代理。
- deploy/runner/{compose.yaml,config.yaml,.env.example}: act_runner v0.6.1 跑在容器里
  (不需要 root), network: host + 同路径挂载部署克隆 + 宿主 docker CLI/compose 插件,
  capacity 1 保证部署串行。
- .gitea/workflows/deploy.yml: push main + workflow_dispatch, [skip deploy] 跳过,
  concurrency 串行, 只做"同步到 github.sha + 调 auto-deploy.sh"。
- .gitignore: deploy/.state/、deploy/runner/{.env,data/}。

依据见 deploy/ci-cd.md(含全部实测证据与待确认项)。
2026-09-13 22:09:32 +08:00
admin ea3ad2bb31 docs: 修正 CI/CD 方案的前提 —— 本机可完整访问互联网
之前测的是错的: 我把 --noproxy '*' 和 -x 一起传给 curl, 等于把要测的代理关掉了,
再叠加当时的一过性网络抖动, 得出了"宿主与容器都上不了外网"的错误结论。重测(2026-09-13):

- 宿主: 国内直连 200, 境外经 127.0.0.1:7890 代理 200;
- 容器: 直连 dl.gitea.com 200 / api.github.com 200 / codeload 301
  (仅 github.com 主站直连会超时), 即容器本来就有网, 不需要代理;
- docker daemon 已配代理(/etc/systemd/system/docker.service.d/http-proxy.conf),
  镜像拉取正常: gitea/act_runner:latest 拉到 arm64 v0.6.1(69.3MB),
  docker.gitea.com/runner-images:ubuntu-22.04 等 job 镜像 manifest 均可取;
- 用 act_runner 镜像自带的 generate-config 确认了两个关键能力:
  label 支持 ":host"(宿主模式), container.network 支持 "host"。

据此重写 deploy/ci-cd.md:
- 主方案改为标准做法: runner 用 gitea/act_runner 容器 + compose 管理,
  job 跑在容器里(network: host, 同路径挂载部署克隆与 docker.sock),
  全程不需要 root(ymy 在 docker 组); 宿主二进制 + host 模式降为备选 B
- 去掉了"离线"带来的一堆绕路(一次性下载二进制、不能写 uses: 等);
  不写 uses: 仍保留, 但理由改成"本项目不需要 + 避开 github.com 主站直连超时",
  并给出需要时的 github_mirror / 代理两条路
- 待确认项从 6 条缩到 3 条实质问题(fork PR 审批、job 镜像工具、workflow 语法支持面)

同时修正 compose/README/.env.example 里"容器上不了外网"的措辞:
默认不用代理的真正理由是"容器直连就通、且宿主 7890 只监听回环容器不可达",
而不是"外网不通"。显式空值挡 compose 自动注入的结论不变。
2026-09-13 17:27:47 +08:00
admin a65970303f docs: 新增 CI/CD 方案(deploy/ci-cd.md): main 推送经 Gitea Actions 自动部署
只写方案, 不落地(workflow 以代码块形式放在文档里, 避免没有 runner 时
push 触发一直挂在"等待 runner")。

要点(都基于本机实测 + 1.27.3 源码):
- runner 必须是"宿主上的 act_runner 二进制 + host 模式": 离线环境下容器模式
  既拉不到 job 镜像, 镜像里也没有 python3/git/docker CLI; host 模式下 job 直接
  以 ymy 在宿主执行, 路径/工具全现成
- 工作流不写 uses:: DEFAULT_ACTIONS_URL 默认指向 github.com, 离线拿不到
  actions/checkout; 同步代码用 run: 里的 git
- 免凭据: 从 /srv/gitea/git/repositories/course-team/tjhlp-gitea.git 直接 fetch
  (实测 git -c safe.directory 对本机 git 无效, 必须写进配置文件)
- 部署逻辑放 deploy/scripts/auto-deploy.sh(可版本化/可手工跑), workflow 只做
  "同步到 github.sha + 调脚本"; build.py 失败不碰容器, 验证失败自动回滚
- 落地步骤分 4 阶段: 下载 runner(需一次外网) -> 部署克隆 -> sudo 装 systemd
  单元并注册(仓库级 runner, API 已确认存在) -> 先 workflow_dispatch 手动跑通
  再打开 push 触发 + main 分支保护
- 明确写出 host 模式的安全含义(等价 root)、待落地确认项(host 标签语法/fork PR
  审批等)与备选方案(cron 轮询)

deploy/README.md 快速索引加一行指向该文档。
2026-09-13 16:59:39 +08:00
admin b60e5e9f1e fix: 容器默认不用出站代理(实测确认不需要)
上一版把代理默认值设成了改造前宿主机上的 10.80.42.185:7890, 实测其实是多余的:

- 与功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连 200;
- 容器里会访问外网的只有「检查更新」(纯提示)和个别学生仓库的 webhook
  (Heai/Test-Webhooks -> heai.ink, jkljkluiouio/hw02 -> debianapi.*),
  课程平台自身与课程仓库都不依赖;
- 宿主 7890 是 ssh 转发的开发用代理, ss -ltn 显示只监听 127.0.0.1/[::1],
  容器两条路都连不上(127.0.0.1:7890 是容器自己的回环, 10.80.42.185:7890
  curl -x 直接 Could not connect) —— 配上只会让每次出站先绕一圈再失败。

改成 ${GITEA_HTTP_PROXY:-} 这种空默认值: 仍然显式赋值以挡住 compose 的自动注入
(注入 127.0.0.1:7890 会让 OIDC discovery 失败、登录 404), 但容器里不再配代理。
将来有稳定且容器可达的代理时, 在 deploy/.env 里给 GITEA_HTTP_PROXY 即可。

实测: 重建后容器内 http_proxy 为空, OIDC 入口 307 -> /oidc/auth, healthz 200,
启动无 [E]; 预览 check 全过。
2026-09-13 16:40:01 +08:00
admin 25f1ec6cfc fix: 固定容器出站代理(修复 OIDC 登录 404); 并关闭通行密钥
1) 出站代理 —— 这次实际踩到的故障:
   docker compose 会把「运行 compose 的那个 shell」里的 http_proxy/https_proxy
   自动注入容器。登录 shell 里是 127.0.0.1:7890, 而 127.0.0.1 在容器里指向容器自己,
   于是 Gitea 启动时 OIDC discovery 失败:
     initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
     proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused
   认证源注册不上 -> 登录页按钮照旧显示(数据来自数据库), 但点下去
   /QA/user/oauth2/... 返回 404, 统一身份认证完全无法登录。
   现在两处 compose 都显式给出这四个变量(默认 = 改造前宿主机上的代理设置,
   NO_PROXY 含 10.80.42.185 让 OIDC 直连), 显式赋值可挡住自动注入;
   .env.example 说明如何覆盖/置空, README 记为新陷阱 6(含一行验证命令)。

2) 通行密钥: [service] ENABLE_PASSKEY_AUTHENTICATION=false(两处 compose)。
   登录页此前那个"空方框"就是它: 上游该区块只有 tw-hidden 元素, 浏览器不支持
   条件中介时 CSS 隐藏一切, 只剩一个带边框的 segment。关掉后连区块都不再输出。

实测: 生产 up -d 后 OIDC 入口 307 -> https://cpp.tongji.sh/oidc/auth?client_id=tjhlp-gitea...
(修复前是 404), 登录页 200 且两张卡片正常, healthz 200。
2026-09-13 16:31:40 +08:00
admin e489d19cb6 feat: 登录页改为「统一身份认证」优先 + 独立的「管理员登录」卡片
整文件覆盖 templates/user/auth/signin.tmpl(基线已进 upstream/):

- 第一张卡: 站名 + 说明文字 + 认证源按钮。按钮部分仍复用上游的
  {{template "user/auth/external_auth_methods" .}}, 所以换/加认证源不用改模板
- 第二张卡: 「管理员登录」, 正文写明此入口仅管理员与助教使用(本地账号),
  同学们请走统一身份认证 —— 避免同学拿学号去试用户名/密码
- 不再渲染 passkey 区块; 表单字段/验证码/忘记密码/记住设备/注册入口保持上游逻辑,
  仅去掉 autofocus(避免聚焦到次要卡片), 实测登录与报错提示均正常

配套:
- preview.sh check 增加登录页断言(有管理员卡片、无通行密钥方框), 现 15 项全过
- README 新增 3.4 登录页(含「预览里临时加认证源」的做法)、目录树与已验证清单
2026-09-11 17:28:34 +08:00
33 changed files with 1699 additions and 141 deletions
+54
View File
@@ -0,0 +1,54 @@
# main 推送后自动部署到 10.80.42.185/QA。
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
# 详见 deploy/ci-cd.md。
name: deploy
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: deploy-main
cancel-in-progress: false
permissions:
contents: read
jobs:
deploy:
# 只认 main 的 push 或手动触发; 提交信息含 [skip deploy] 则跳过
if: >-
github.event_name == 'workflow_dispatch' ||
(github.ref == 'refs/heads/main' &&
!contains(github.event.head_commit.message, '[skip deploy]'))
runs-on: self-hosted
timeout-minutes: 30
# ★ 宿主能力(docker socket、部署克隆、裸库、docker CLI)由【本 job】申报,而不是由
# runner 全局发给每个 job。runner 侧的 container.valid_volumes 是允许清单:
# 没列进去的挂载会被丢弃,所以这里的每一项都要在 deploy/runner/config.yaml 里有对应项。
# 将来加 PR 检查/测试 workflow 时,那个 job 不申报就什么都拿不到(无 socket = 无 root)。
container:
volumes:
- /home/ymy/deploy:/home/ymy/deploy # 工作目录(auto-deploy.sh 要写 .state)
- /srv/gitea:/srv/gitea:ro # deploy 克隆的 origin(本地裸库)
- /var/run/docker.sock:/var/run/docker.sock # docker compose up -d
- /usr/bin/docker:/usr/bin/docker:ro # 宿主 docker CLI
- /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro # compose 插件
steps:
- name: 同步到目标提交
run: |
set -euo pipefail
cd /home/ymy/deploy/tjhlp-gitea
git fetch --prune origin
# -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
# 若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
git checkout -f --detach "${{ github.sha }}"
git --no-pager log --oneline -1
- name: 构建并部署(失败自动回滚)
run: |
set -euo pipefail
# 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
# 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
cd /home/ymy/deploy/tjhlp-gitea
./deploy/scripts/auto-deploy.sh
+4
View File
@@ -17,6 +17,10 @@ credentials_*.csv
# Deployment (docker compose) # Deployment (docker compose)
deploy/.env deploy/.env
deploy/backups/ deploy/backups/
# CI/CD: 部署状态(上次成功的 SHA)与 runner 的注册凭据/缓存
deploy/.state/
deploy/runner/.env
deploy/runner/data/
# Customization # Customization
customization/custom/options/locale/locale_zh-CN.json customization/custom/options/locale/locale_zh-CN.json
+2 -1
View File
@@ -123,7 +123,8 @@ yamllint issue-templates/ # YAML 语法
python3 customization/build.py # 生成定制语言文件 python3 customization/build.py # 生成定制语言文件
python3 customization/build.py --check # 校验生成物是否最新 python3 customization/build.py --check # 校验生成物是否最新
customization/preview/preview.sh up # 起本地预览(127.0.0.1:2081) customization/preview/preview.sh up # 起本地预览(127.0.0.1:2081)
customization/preview/preview.sh check # 自动校验首页/页脚/meta/术语 customization/preview/preview.sh semester # 造一个学期组织, 看首页答疑入口卡片
customization/preview/preview.sh check # 自动校验首页/登录页/卡片/页脚/meta/术语
``` ```
机制调查、日常改法与部署/升级流程见 [`customization/README.md`](customization/README.md); 机制调查、日常改法与部署/升级流程见 [`customization/README.md`](customization/README.md);
+89 -14
View File
@@ -68,7 +68,10 @@ Gitea 把模板 / 语言 / 静态资源都编进了二进制,但读取时走 `as
| 首页指向 | `[server] LANDING_PAGE` | `GITEA__server__LANDING_PAGE` | | 首页指向 | `[server] LANDING_PAGE` | `GITEA__server__LANDING_PAGE` |
| meta 作者/描述/关键词 | `[ui.meta] AUTHOR/DESCRIPTION/KEYWORDS` | `GITEA__ui_0X2E_meta__DESCRIPTION` 等 | | 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` | | 页脚 Powered by / 版本号 | `[other] SHOW_FOOTER_POWERED_BY` / `SHOW_FOOTER_VERSION` | `GITEA__other__SHOW_FOOTER_POWERED_BY` |
| Issue 显示姓名而非学号 | `[ui] DEFAULT_SHOW_FULL_NAME` | `GITEA__ui__DEFAULT_SHOW_FULL_NAME` |
| 自定义主题配色 | `[ui] THEMES` + `custom/public/assets/css/theme-*.css` | `GITEA__ui__THEMES` | | 自定义主题配色 | `[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` 等 | 同上(文件方式) | | Logo / favicon | 放 `custom/public/assets/img/{logo,favicon}.svg` 等 | 同上(文件方式) |
> 环境变量规则:`GITEA__<段名>__<键名>`,段名里的 `.` 不能直接写,要编码成 > 环境变量规则:`GITEA__<段名>__<键名>`,段名里的 `.` 不能直接写,要编码成
@@ -103,7 +106,10 @@ customization/
├── custom/ ★ 挂进容器的覆盖层(= $CustomPath 的内容) ├── custom/ ★ 挂进容器的覆盖层(= $CustomPath 的内容)
│ ├── templates/home.tmpl 落地页 │ ├── templates/home.tmpl 落地页
│ ├── templates/base/head_navbar.tmpl 导航栏(去掉 docs.gitea.com) │ ├── templates/base/head_navbar.tmpl 导航栏(去掉 docs.gitea.com)
│ ├── public/assets/tjhlp/ask-guide.html 静态「提问指南」页(/assets/tjhlp/...) │ ├── templates/user/auth/signin.tmpl 登录页(统一身份认证优先, 管理员登录次要)
│ ├── templates/user/dashboard/dashboard.tmpl 首页(登录后); 只比上游多一行 include
│ ├── templates/custom/tjhlp_semester_card.tmpl ★ 首页顶部的学期答疑入口卡片(自己写的)
│ ├── public/.gitkeep 占位(提问指南已只在官网, 目录留作将来放静态资源)
│ └── options/locale/locale_zh-CN.json 生成物,已 gitignore │ └── options/locale/locale_zh-CN.json 生成物,已 gitignore
└── preview/ 本地预览(独立 compose,独立端口/数据) └── preview/ 本地预览(独立 compose,独立端口/数据)
├── compose.yaml ├── compose.yaml
@@ -165,6 +171,62 @@ customization/preview/preview.sh reset # 清空预览数据重新来
- **模板改动仍需重启**(`reload`),这是 Gitea 的既有行为。 - **模板改动仍需重启**(`reload`),这是 Gitea 的既有行为。
- 需要 docker 权限;当前 shell 不在 docker 组时脚本会自动改用 `sg docker -c`。 - 需要 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. 纳入当前项目 & 部署
@@ -199,6 +261,8 @@ GITEA_CUSTOM_DIR=../customization/custom
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
GITEA__other__SHOW_FOOTER_POWERED_BY: "false" GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false" GITEA__other__SHOW_FOOTER_VERSION: "false"
# Issue 发布者/评论者显示姓名(导入时 full_name=姓名, login=学号)
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
``` ```
设计取舍: 设计取舍:
@@ -217,17 +281,22 @@ GITEA_CUSTOM_DIR=../customization/custom
| 位置 | 内容 | 文件 | | 位置 | 内容 | 文件 |
| ------ | ------ | ------ | | ------ | ------ | ------ |
| 导航栏(未登录) | 「课程官网」 | `custom/templates/base/head_navbar.tmpl` | | 导航栏(未登录) | 「课程官网」/「提问指南」 | `custom/templates/base/head_navbar.tmpl` |
| 用户菜单(已登录) | 「课程官网」 | 同上 | | 用户菜单(已登录) | 「课程官网」/「提问指南」 | 同上 |
| 首页「按模板提问」卡片 | 官网《学会提问》 | `custom/templates/home.tmpl` | | 首页「按模板提问」卡片 | 官网《提问指南》 | `custom/templates/home.tmpl` |
| 首页底部「相关站点」 | 官网 / 学会提问 / 常见问题 / 联系我们 | 同上 | | 首页底部「相关站点」 | 官网 / 提问指南 / 常见问题 / 联系我们 | 同上 |
| 站内提问指南页 | 顶部提示与底部「相关站点」 | `custom/public/assets/tjhlp/ask-guide.html` | | 首页答疑入口卡片 | 官网《提问指南》 | `custom/templates/custom/tjhlp_semester_card.tmpl` |
| 新建 Issue 页的引导链接 | 学会提问 / 课程官网 / 平台速查 | `issue-templates/*/.gitea/ISSUE_TEMPLATE/config.yaml` | | 新建 Issue 页的引导链接 | 提问指南 / 课程官网 | `issue-templates/*/.gitea/ISSUE_TEMPLATE/config.yaml` |
> **改地址时要一起改的地方**:官网地址 `https://cpp.tongji.sh/Website/` 在上表前三行的文件 官网地址 `https://cpp.tongji.sh/Website/` 出现在上表列出的模板与两个 `config.yaml` 里;
> 与两个 `config.yaml` 里各出现一次;平台自身地址只在 平台自身地址只在 `scripts/settings.toml` 的 `gitea.public_url` 里维护一处(Issue 模板里的
> `scripts/settings.toml` 的 `gitea.public_url` 里维护一处(Issue 模板里的 `{{BASE_URL}}` 在推送时替换)。
> `{{BASE_URL}}` 在推送时替换)。
> **提问指南只在官网保留一份**(`/Website/qa/ask/`):平台内原来的副本
> `custom/public/assets/tjhlp/ask-guide.html` 已在 2026-09 删除, 相关链接全部指向官网。
> 官网 2026-09 改版后的路径: 提问指南 `/Website/qa/ask/`、常见问题 `/Website/qa/faq/`、
> 联系我们 `/Website/contact.html`; 旧的 `/Website/ask-question/`、`/Website/faq/`
> 只是跳转页, `/Website/contact` 已经 404 —— 不要再写这些旧地址。
反向的入口(官网 → 平台)在 Website 仓库里,方案见 反向的入口(官网 → 平台)在 Website 仓库里,方案见
[`website-linkage.md`](website-linkage.md)。 [`website-linkage.md`](website-linkage.md)。
@@ -291,14 +360,20 @@ cd deploy && ./scripts/backup.sh --quiesce && docker compose pull gitea && docke
- ✅ 落地页替换为定制 `home.tmpl`(4 张卡片、无 Gitea 功能介绍) - ✅ 落地页替换为定制 `home.tmpl`(4 张卡片、无 Gitea 功能介绍)
- ✅ `[ui.meta]` 元信息替换(`GITEA__ui_0X2E_meta__*` 编码有效) - ✅ `[ui.meta]` 元信息替换(`GITEA__ui_0X2E_meta__*` 编码有效)
- ✅ 页脚 Powered by / 版本号可关闭 - ✅ 页脚 Powered by / 版本号可关闭
- ✅ 导航栏 `docs.gitea.com` 外链替换为课程提问指南(整文件覆盖 `head_navbar.tmpl`) - ✅ 导航栏 `docs.gitea.com` 外链替换为官网《提问指南》(`/Website/qa/ask/`)
- ✅ `custom/public/assets/tjhlp/ask-guide.html` 经 `/assets/` 正常访问 - ✅ 平台内 `public/assets/tjhlp/ask-guide.html` 已删除, 页面与 Issue 模板全部指向官网
- ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」 - ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」
- ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启) - ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启)
- ✅ 登录页改成「统一身份认证」优先 + 「管理员登录」卡片,表单仍可正常登录/报错
- ✅ 关闭 `ENABLE_PASSKEY_AUTHENTICATION` 后,登录页不再出现空的通行密钥方框
- ✅ 首页(登录后)顶部出现学期答疑入口卡片: 只认 `tjhlp-<5 位数字>`、取最新学期、
无匹配则不显示(预览里用 3 个用户 × 4 个组织验证过)
- ✅ 打开 `[ui] DEFAULT_SHOW_FULL_NAME` 后, Issue 的「由 X 创建」与正文/评论作者
显示 `full_name`(姓名), 未填姓名的用户回退显示 login(学号)(预览实测)
尚未覆盖(需要时按同样套路加): 尚未覆盖(需要时按同样套路加):
- Logo / favicon 换成本课程的图(需要设计稿;放到 `custom/public/assets/img/`) - Logo / favicon 换成本课程的图(需要设计稿;放到 `custom/public/assets/img/`)
- 登录页、注册页、错误页文案 - 注册页(`user/auth/signup.tmpl`)、错误页文案
- 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 `overrides/` 里加规则即可 - 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 `overrides/` 里加规则即可
- 自定义主题配色(`[ui] THEMES` + `custom/public/assets/css/theme-*.css`) - 自定义主题配色(`[ui] THEMES` + `custom/public/assets/css/theme-*.css`)
+8
View File
@@ -188,7 +188,15 @@ def main() -> int:
return 0 return 0
OUT_PATH.parent.mkdir(parents=True, exist_ok=True) OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
try:
OUT_PATH.write_text(rendered, encoding="utf-8") OUT_PATH.write_text(rendered, encoding="utf-8")
except PermissionError as exc:
raise SystemExit(
f"写入失败: {exc}\n"
f" 多半是 docker 以 root 创建过这个挂载源目录(bind mount 的源目录不存在时它会这么做),\n"
f" 普通用户就写不进去了。删掉再重试: sudo rm -rf {OUT_PATH.parent}\n"
f" (仓库里 customization/custom/options/.gitkeep 就是为防止这种情况而存在的)"
) from exc
print(f"✓ 已生成 {OUT_PATH}") print(f"✓ 已生成 {OUT_PATH}")
fixed = ensure_readable(CUSTOM_DIR) fixed = ensure_readable(CUSTOM_DIR)
if fixed: if fixed:
+131
View File
@@ -0,0 +1,131 @@
#!/usr/bin/env bash
# 定制生效断言 —— 对任意实例跑一遍, 预览与生产共用。
# 用法:
# customization/check.sh http://127.0.0.1:2081 # 预览
# customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里也调这个)
#
# 退出码: 0 全通过 / 1 有断言失败 / 2 用法错误。
# 只读: 只发 GET, 不改任何东西。
set -uo pipefail
BASE_URL="${1:-}"
if [[ -z ${BASE_URL} ]]; then
sed -n '2,9p' "$0"
exit 2
fi
BASE_URL="${BASE_URL%/}"
ORIGIN="$(printf '%s' "${BASE_URL}" | sed -E 's#(^https?://[^/]+).*#\1#')"
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
fail=0
ok() { printf ' ✓ %s\n' "$1"; }
bad() {
printf ' ✗ %s\n' "$1"
fail=1
}
skip() { printf ' – %s\n' "$1"; }
tmp="$(mktemp -d)"
trap 'rm -rf "${tmp}"' EXIT
# --noproxy: 验证目标都在内网, 走代理只会把 200 变成 502(见 deploy/README.md 陷阱 5)
curl_() { curl -sS --noproxy '*' --max-time 20 "$@"; }
echo "== 定制检查 ${BASE_URL} =="
# --- 首页 -------------------------------------------------------------------
if ! curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/" -o "${tmp}/home.html"; then
echo " ✗ 首页打不开(HTTP 非 2xx), 后面不再检查"
exit 1
fi
ok "首页可访问"
grep -q "先搜索,再提问" "${tmp}/home.html" &&
ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${tmp}/home.html" &&
ok "导航栏/首页已指向官网提问指南(/Website/qa/ask/)" ||
bad "没找到官网提问指南链接(页面还是旧模板? 模板改动要重启 gitea 才生效)"
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${tmp}/home.html" &&
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
! grep -qi "powered by" "${tmp}/home.html" &&
ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
! grep -q "docs.gitea.com" "${tmp}/home.html" &&
ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${tmp}/home.html" &&
ok "meta description 已替换" || bad "meta description 未替换"
# --- 与课程官网的联动 -------------------------------------------------------
grep -q "https://cpp.tongji.sh/Website/" "${tmp}/home.html" &&
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${tmp}/home.html" &&
ok "首页已链接官网提问指南" || bad "首页没有官网提问指南链接"
! grep -q "Website/ask-question/\|Website/faq/\|Website/contact\"" "${tmp}/home.html" &&
ok "没有指向官网已迁移/失效的旧地址" ||
bad "仍有旧地址(ask-question / faq / contact 无 .html)"
# 站内提问指南页已按决定删除: 提问指南只在官网保留一份
if curl_ -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" 2>/dev/null; then
bad "平台内还留着 ask-guide.html(提问指南应只在官网)"
else
ok "平台内提问指南页已删除"
fi
# --- 中文术语与登录页 -------------------------------------------------------
if curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/user/login" -o "${tmp}/login.html"; then
ok "登录页可访问"
grep -q "管理员登录" "${tmp}/login.html" &&
ok "登录页有独立的「管理员登录」卡片" || bad "登录页缺少管理员登录卡片"
! grep -q "webauthn-error\|signin-passkey" "${tmp}/login.html" &&
ok "登录页已无空的通行密钥(WebAuthn)方框" || bad "登录页仍有通行密钥区块"
# OIDC 入口: 配了认证源的实例才会渲染 external-login-navigator
if grep -q 'id="external-login-navigator"' "${tmp}/login.html"; then
href="$(grep -o 'href="[^"]*/user/oauth2/[^"]*"' "${tmp}/login.html" | head -1 |
sed -E 's/^href="//; s/"$//')"
if [[ -z ${href} ]]; then
bad "登录页有认证源区块但没解析出 OAuth2 链接"
else
code="$(curl_ -o /dev/null -w '%{http_code}' "${ORIGIN}${href}")"
# 307 = 认证源注册成功并跳转统一身份认证; 404 = 认证源没注册上(见 README 陷阱 6)
[[ ${code} == 307 ]] &&
ok "OIDC 入口 ${href} 返回 307(跳转统一身份认证)" ||
bad "OIDC 入口返回 ${code}, 期望 307(404 = 认证源没注册上)"
fi
else
skip "该实例未配置认证源, 跳过 OIDC 入口检查(预览实例属此情况)"
fi
else
bad "登录页打不开"
fi
# 术语: 中文界面里不该再出现「工单」
if curl_ -fsS -H 'Accept-Language: zh-CN' -o "${tmp}/issues.html" \
"${BASE_URL}/course-team/tjhlp-gitea/issues"; then
! grep -q "工单" "${tmp}/issues.html" &&
ok "Issue 列表页中文界面已无「工单」" || bad "Issue 列表页仍有「工单」"
else
skip "读不到 issue 列表页(需要登录?), 跳过「工单」检查"
fi
# --- 仓库内文件(在 checkout 里跑时才有意义) --------------------------------
if [[ -d ${ROOT}/issue-templates ]]; then
! grep -rq "example.com" "${ROOT}/issue-templates/" &&
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
fi
if [[ -f ${ROOT}/customization/custom/options/locale/locale_zh-CN.json ]]; then
! grep -q "工单" "${ROOT}/customization/custom/options/locale/locale_zh-CN.json" &&
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
fi
# 首页(登录后)的学期答疑入口卡片: 渲染结果需要登录才能看, 这里只断言模板层
# (运行时的渲染断言在 customization/preview/preview.sh check 里, 要登录)。
if [[ -f ${ROOT}/customization/custom/templates/custom/tjhlp_semester_card.tmpl ]]; then
grep -q "本学期答疑入口" "${ROOT}/customization/custom/templates/custom/tjhlp_semester_card.tmpl" &&
ok "首页答疑入口卡片模板在位" || bad "卡片模板里没有预期的内容"
grep -q 'template "custom/tjhlp_semester_card"' \
"${ROOT}/customization/custom/templates/user/dashboard/dashboard.tmpl" &&
ok "dashboard.tmpl 已 include 学期答疑入口卡片" || bad "dashboard.tmpl 没有 include 卡片"
fi
if [[ ${fail} == 0 ]]; then
echo "全部检查通过"
else
echo "存在检查未通过项"
fi
exit "${fail}"
+15
View File
@@ -0,0 +1,15 @@
# 这个文件唯一的用途: 让 git 跟踪住这个空目录。
#
# customization/custom/ 下的三个子目录会被逐个 bind mount 进容器:
# custom/options -> /data/gitea/options
# custom/public -> /data/gitea/public
# custom/templates-> /data/gitea/templates
# 如果 options/ 在全新克隆里不存在(它下面只放生成出来的 locale_zh-CN.json, 而那个文件
# 是 gitignore 的), 那么 docker compose 会【以 root 创建】这个挂载源目录 —— 之后
# 普通用户跑 customization/build.py 就写不进去:
# PermissionError: [Errno 13] Permission denied: .../custom/options/locale
# 于是语言文件永远生成不出来, 中文界面退回上游文案(「工单」又回来了)。
# 2026-09-13 第一次把生产切到部署克隆时真实踩到。
#
# 有了这个占位文件, 目录随 checkout 就存在且属于当前用户, 问题从结构上消失。
# 真正有内容的是 custom/templates 与 custom/public, 它们不需要占位。
+15
View File
@@ -0,0 +1,15 @@
# 这个文件唯一的用途: 让 git 跟踪住这个(现在)空的目录。
#
# customization/custom/ 下的三个子目录会被逐个 bind mount 进容器:
# custom/options -> /data/gitea/options
# custom/public -> /data/gitea/public
# custom/templates-> /data/gitea/templates
#
# public/ 原来放的是站内「提问指南」静态页
# (public/assets/tjhlp/ask-guide.html)。2026-09 起提问指南只在课程官网保留一份
# (https://cpp.tongji.sh/Website/qa/ask/), 平台内的副本已删除, 这个目录就空了。
# 目录不能跟着消失: bind mount 的源目录不存在时 docker compose 会【以 root 创建】它,
# 之后普通用户/CI 都用不了(同样的坑见 options/.gitkeep)。
#
# 将来要往平台里放静态资源时, 直接加在 public/ 下即可(例如
# public/assets/img/logo.svg -> /QA/assets/img/logo.svg)。
@@ -1,88 +0,0 @@
<!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>
@@ -43,7 +43,7 @@
{{if not .IsSigned}} {{if not .IsSigned}}
<a class="item" href="https://cpp.tongji.sh/Website/">课程官网</a> <a class="item" href="https://cpp.tongji.sh/Website/">课程官网</a>
<a class="item" href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html">提问指南</a> <a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a>
{{end}} {{end}}
</div> </div>
@@ -126,7 +126,7 @@
{{svg "octicon-tools"}} {{svg "octicon-tools"}}
{{ctx.Locale.Tr "your_settings"}} {{ctx.Locale.Tr "your_settings"}}
</a> </a>
<a class="item" href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html"> <a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">
{{svg "octicon-question"}} {{svg "octicon-question"}}
提问指南 提问指南
</a> </a>
@@ -0,0 +1,56 @@
{{/*
首页(登录后的仪表盘)顶部的「本学期答疑入口」大卡片。
这是本课程自己的模板, 不是上游文件; 插入点见
custom/templates/user/dashboard/dashboard.tmpl(只比上游多一行 include)。
逻辑:
* .Orgs = 当前用户所属的全部组织, 由 routers/web/user/home.go 的 Dashboard
处理器注入(organization.GetUserOrgsList, 按 lower_name 升序);
* 「学期组织」的判定 = 名字形如 tjhlp-<5 位数字>, 例如
tjhlp-26271 = 2026-2027 学年第一学期(26|27|1)
旧命名 tjhlp-2026s 这种带字母的不算, 也不认其它前缀的组织;
* 取其中名字最大(即最新学期)的一个;
* 渲染成一张约 1/3 屏高的大卡片, 按钮直达该组织的 general 仓库 Issue 区。
匹配不上就整张卡片不显示: 宁可什么都不显示, 也不要给同学一个错的入口。
改判定规则/文案只需要动这个文件(不要动 dashboard.tmpl 的其余部分)。
*/}}
{{$semester := ""}}
{{range .Orgs}}
{{$name := .Name}}
{{$code := StringUtils.TrimPrefix $name "tjhlp-"}}
{{if and
(ne $code $name)
(eq (len $code) 5)
(StringUtils.Contains "0123456789" (slice $code 0 1))
(StringUtils.Contains "0123456789" (slice $code 1 2))
(StringUtils.Contains "0123456789" (slice $code 2 3))
(StringUtils.Contains "0123456789" (slice $code 3 4))
(StringUtils.Contains "0123456789" (slice $code 4 5))}}
{{if or (eq $semester "") (gt $name $semester)}}{{$semester = $name}}{{end}}
{{end}}
{{end}}
{{if $semester}}
{{$code := StringUtils.TrimPrefix $semester "tjhlp-"}}
{{$term := slice $code 4 5}}
{{$termText := printf "第%s学期" $term}}
{{if eq $term "1"}}{{$termText = "第一学期"}}{{else if eq $term "2"}}{{$termText = "第二学期"}}{{end}}
{{$label := printf "20%s-20%s 学年%s" (slice $code 0 2) (slice $code 2 4) $termText}}
<div class="ui container tw-mb-4">
{{/* 33vh ≈ 屏幕纵向的 1/3; 用行内样式, 不依赖 Tailwind 是否收录了某个工具类 */}}
<div class="ui segment" style="min-height:33vh;display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:1rem;padding:1.5rem 1rem">
<h2 style="margin:0">本学期答疑入口</h2>
<p style="margin:0;color:var(--color-text-light-2)">
课程问题请进入下面的答疑区提问(一条 Issue 一个问题), 助教与老师会在那里回复。
</p>
<a class="ui primary fluid button" style="font-size:1.35rem;padding:1rem;max-width:34rem"
href="{{AppSubUrl}}/{{$semester}}/general/issues">
进入{{$label}}答疑区
</a>
<p style="margin:0;color:var(--color-text-light-2)">
第一次提问? 先看课程官网的<a href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a>
</p>
<p style="margin:0;color:var(--color-text-light-3);font-size:.85rem">学期组织: {{$semester}}</p>
</div>
</div>
{{end}}
+9 -8
View File
@@ -7,9 +7,10 @@
* 文案直接写中文(平台只面向中文用户), 不复用 Gitea 的 startpage.* 文案, * 文案直接写中文(平台只面向中文用户), 不复用 Gitea 的 startpage.* 文案,
这样首页不再出现「一款极易搭建的自托管 Git 服务」之类的自我推销。 这样首页不再出现「一款极易搭建的自托管 Git 服务」之类的自我推销。
* 只改文案/图标/链接, 保留原有 class 与结构, 避免升级后样式失效。 * 只改文案/图标/链接, 保留原有 class 与结构, 避免升级后样式失效。
* 课程官网地址 https://cpp.tongji.sh/Website/ 在本文件、base/head_navbar.tmpl、 * 课程官网地址 https://cpp.tongji.sh/Website/ 出现在本文件、base/head_navbar.tmpl、
public/assets/tjhlp/ask-guide.html 以及 issue-templates 下两个 config.yaml 里 custom/tjhlp_semester_card.tmpl 以及 issue-templates 下两个 config.yaml 里,
各出现一次, 换域名/路径时这几处要一起改(见 customization/README.md「与官网联动」)。 换域名/路径时这几处要一起改(见 customization/README.md「与官网联动」)。
提问指南只在官网存一份: /Website/qa/ask/ —— 平台内不再保留副本(2026-09 起)。
*/}} */}}
{{template "base/head" .}} {{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 role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
@@ -41,8 +42,8 @@
</h1> </h1>
<p class="large tw-text-balance"> <p class="large tw-text-balance">
新建 Issue 时请选择合适的模板,写清题号、相关代码、报错信息和已经尝试过的做法。 新建 Issue 时请选择合适的模板,写清题号、相关代码、报错信息和已经尝试过的做法。
提问规范见课程官网<a href="https://cpp.tongji.sh/Website/ask-question/">《学会提问》</a>, 提问规范与具体做法见课程官网的
平台操作见<a href="{{AppSubUrl}}/assets/tjhlp/ask-guide.html">提问指南</a>。 <a href="https://cpp.tongji.sh/Website/qa/ask/">《提问指南》</a>。
</p> </p>
</div> </div>
</div> </div>
@@ -70,9 +71,9 @@
<p class="large"> <p class="large">
相关站点: 相关站点:
<a href="https://cpp.tongji.sh/Website/">课程官网</a> · <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/qa/ask/">提问指南</a> ·
<a href="https://cpp.tongji.sh/Website/faq/">常见问题</a> · <a href="https://cpp.tongji.sh/Website/qa/faq/">常见问题</a> ·
<a href="https://cpp.tongji.sh/Website/contact">联系我们</a> <a href="https://cpp.tongji.sh/Website/contact.html">联系我们</a>
</p> </p>
<p> <p>
<small>本平台只用于课程答疑,课程通知、作业要求等以课程官网与课程群为准。</small> <small>本平台只用于课程答疑,课程通知、作业要求等以课程官网与课程群为准。</small>
@@ -0,0 +1,92 @@
{{/*
登录页, 整文件覆盖 Gitea 内置 templates/user/auth/signin.tmpl。
维护约定:
* 上游基线: customization/upstream/<版本>/templates/user/auth/signin.tmpl
升级 Gitea 时先 diff 基线, 把上游的结构性改动(新增表单字段/新认证方式)合并回来。
* 相对上游的改动只有布局, 逻辑尽量原样搬过来:
1) 课程同学走的是「高程统一身份认证」(OIDC), 所以把它放进第一张卡片、配说明文字;
卡片正文复用上游的 {{template "user/auth/external_auth_methods" .}},
将来新增/更换认证源不用改这个模板。
2) 用户名/密码降级为第二张「管理员登录」卡片, 并在正文里写明只有管理员/助教用。
3) 不再渲染通行密钥(passkey)区块 —— 上游那块只有 tw-hidden 的元素, 浏览器不支持
条件中介时会留下一个空的方框; 服务端已用
[service] ENABLE_PASSKEY_AUTHENTICATION = false 关掉该功能。
* 只用 Gitea 已编译进 CSS 的 class: Tailwind 工具类是按上游模板裁剪过的,
新增 tw-* 前先 grep assets/css/index.css 确认存在(否则不会生效)。
* 文案直接写中文(平台只面向中文用户), 表单标签仍走 ctx.Locale.Tr 以便跟随语言设置。
*/}}
{{template "base/head" .}}
<div role="main" aria-label="{{.Title}}" class="page-content user signin">
<div class="ui middle very relaxed page grid">
{{/* 这些样式与内置模板保持一致, 同时作用于登录/注册/绑定账号页 */}}
<div class="column tw-flex tw-flex-col tw-gap-4 tw-max-w-2xl tw-m-auto">
<div class="ui container fluid">
{{template "base/alert" .}}
</div>
{{$hasExternalAuth := or .OAuth2Providers .EnableOpenIDSignIn .EnableSSPI}}
{{if $hasExternalAuth}}
<div class="ui container fluid">
<h4 class="ui top attached header center">登录 {{AppName}}</h4>
<div class="ui attached segment">
<p class="tw-text-center tw-m-0">
请使用<strong>高程统一身份认证</strong>登录, 账号密码与文档作业网站相同
</p>
{{template "user/auth/external_auth_methods" .}}
</div>
</div>
{{end}}
{{if .EnablePasswordSignInForm}}
<div class="ui container fluid">
<h4 class="ui top attached header center">管理员登录</h4>
<div class="ui attached segment">
<p class="tw-text-center tw-m-0 tw-text-sm">
此入口仅供管理员使用
</p>
<form class="ui form" action="{{.SignInLink}}" method="post">
<div class="required field {{if .Err_UserName}}error{{end}}">
<label for="user_name">{{ctx.Locale.Tr "home.uname_holder"}}</label>
<input id="user_name" type="text" name="user_name" value="{{.user_name}}" required tabindex="1">
</div>
{{if not .DisablePassword}}
<div class="required field {{if .Err_Password}}error{{end}}">
<div class="tw-flex tw-mb-1">
<label for="password" class="tw-flex-1">{{ctx.Locale.Tr "password"}}</label>
<a href="{{AppSubUrl}}/user/forgot_password" tabindex="4">{{ctx.Locale.Tr "auth.forgot_password"}}</a>
</div>
<input id="password" name="password" type="password" value="{{.password}}" autocomplete="current-password" required tabindex="2">
</div>
{{end}}
<div class="inline field">
<div class="ui checkbox">
<label>{{ctx.Locale.Tr "auth.remember_me"}}</label>
<input name="remember" type="checkbox" tabindex="5">
</div>
</div>
{{template "user/auth/captcha" .}}
<div class="field">
<button class="ui primary button tw-w-full" tabindex="3">
{{ctx.Locale.Tr "sign_in"}}
</button>
</div>
</form>
</div>
</div>
{{end}}
{{if .ShowRegistrationButton}}
<div class="ui container fluid">
<div class="ui attached segment tw-text-center">
<span>{{ctx.Locale.Tr "auth.need_account"}}</span>
<a href="{{AppSubUrl}}/user/sign_up">{{ctx.Locale.Tr "auth.sign_up_now"}}</a>
</div>
</div>
{{end}}
</div>
</div>
</div>
{{template "base/footer" .}}
@@ -0,0 +1,22 @@
{{template "base/head" .}}
<div role="main" aria-label="{{.Title}}" class="page-content dashboard feeds">
{{template "user/dashboard/navbar" .}}
{{/* ★ 本课程新增(上游没有这一行): 首页顶部的「本学期答疑入口」卡片。
卡片内容在 custom/templates/custom/tjhlp_semester_card.tmpl;
升级 Gitea 时先 diff upstream/<版本>/templates/user/dashboard/dashboard.tmpl,
确认上游结构变化后把这一行重新插到 navbar 之后即可。 */}}
{{template "custom/tjhlp_semester_card" .}}
<div class="ui container flex-container">
<div class="flex-container-main">
{{template "base/alert" .}}
{{template "user/heatmap" .}}
{{if .Page.Paginater.TotalPages}}
{{template "user/dashboard/feeds" .}}
{{else}}
{{template "user/dashboard/guide" .}}
{{end}}
</div>
{{template "user/dashboard/repolist" .}}
</div>
</div>
{{template "base/footer" .}}
+19
View File
@@ -60,8 +60,22 @@ services:
GITEA__service__DISABLE_REGISTRATION: "false" GITEA__service__DISABLE_REGISTRATION: "false"
GITEA__service__ENABLE_CAPTCHA: "false" GITEA__service__ENABLE_CAPTCHA: "false"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false" GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
# 不做通行密钥(WebAuthn): 上游登录页那块只有 tw-hidden 元素, 浏览器不支持条件中介时
# 会留下一个空的方框; 关掉后区块不再渲染, 登录页也不会出现 passkey 入口。
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "false"
GITEA__mailer__ENABLED: "false" GITEA__mailer__ENABLED: "false"
# --- 出站代理: 显式给值挡掉自动注入, 默认不用代理 ---------------------
# compose 会把宿主 shell 的 http_proxy(本机是 127.0.0.1:7890, 在容器里指向
# 容器自己)自动注入; 生产上这会直接让 OIDC discovery 失败(登录 404)。
# 容器直连外网本身是通的(实测), 不需要代理; 理由见 deploy/compose.yaml 同位置注释。
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
http_proxy: ${GITEA_HTTP_PROXY:-}
https_proxy: ${GITEA_HTTPS_PROXY:-}
NO_PROXY: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
no_proxy: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
# --- 站点元信息与页脚: 去掉 Gitea 自我推销 ------------------------- # --- 站点元信息与页脚: 去掉 Gitea 自我推销 -------------------------
# 段名里的点要写成 _0X2E_ (Gitea 的 GITEA__section__KEY 编码规则) # 段名里的点要写成 _0X2E_ (Gitea 的 GITEA__section__KEY 编码规则)
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程 GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
@@ -70,6 +84,11 @@ services:
GITEA__other__SHOW_FOOTER_POWERED_BY: "false" GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false" GITEA__other__SHOW_FOOTER_VERSION: "false"
# --- 显示名称: 与生产一致, Issue 显示姓名而不是学号 ----------------
# 说明见 deploy/compose.yaml 同位置。这里给上才能让预览里验证
# 「发布者/回答者显示姓名」的效果。
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
GITEA__log__MODE: console GITEA__log__MODE: console
GITEA__log__LEVEL: ${GITEA_LOG_LEVEL:-info} GITEA__log__LEVEL: ${GITEA_LOG_LEVEL:-info}
+71 -9
View File
@@ -8,6 +8,7 @@
# ./preview.sh ps 查看状态 # ./preview.sh ps 查看状态
# ./preview.sh shell 进入容器 # ./preview.sh shell 进入容器
# ./preview.sh admin 在预览实例里建一个管理员(用于验证登录后的页面) # ./preview.sh admin 在预览实例里建一个管理员(用于验证登录后的页面)
# ./preview.sh semester 造一个学期组织(含 general 仓库), 用于看首页的答疑入口卡片
# ./preview.sh check 构建校验 + 首页文案/页脚/元信息抽查 # ./preview.sh check 构建校验 + 首页文案/页脚/元信息抽查
# #
# 说明: 本机 docker 需要 docker 组权限; 当前 shell 没有时会自动改用 # 说明: 本机 docker 需要 docker 组权限; 当前 shell 没有时会自动改用
@@ -86,6 +87,31 @@ admin)
--email "${USERNAME}@example.com" --admin --must-change-password=false --email "${USERNAME}@example.com" --admin --must-change-password=false
echo "管理员: ${USERNAME} / ${PASSWORD}" echo "管理员: ${USERNAME} / ${PASSWORD}"
;; ;;
semester)
# 造一个学期组织 + general 仓库, 用来在预览里验证首页(登录后)的答疑入口卡片。
# 幂等: 已存在就跳过。默认建 tjhlp-26271(2026-2027 学年第一学期 的命名),
# 想验证"只认最新学期/不认旧命名"可以再建几个:
# ./preview.sh semester previewadmin previewadmin123 tjhlp-25261
# ./preview.sh semester previewadmin previewadmin123 tjhlp-2026s
USERNAME="${2:-previewadmin}"
PASSWORD="${3:-previewadmin123}"
ORG="${4:-tjhlp-26271}"
api() { curl -fsS --noproxy '*' -u "${USERNAME}:${PASSWORD}" -H 'Content-Type: application/json' "$@"; }
if api "${BASE_URL}/api/v1/orgs/${ORG}" >/dev/null 2>&1; then
echo "组织 ${ORG} 已存在, 跳过创建"
else
api -X POST -d "{\"username\":\"${ORG}\",\"full_name\":\"${ORG}\"}" "${BASE_URL}/api/v1/orgs" >/dev/null
echo "已创建组织 ${ORG}(创建者即成员, 也就是 ${USERNAME})"
fi
if api "${BASE_URL}/api/v1/repos/${ORG}/general" >/dev/null 2>&1; then
echo "仓库 ${ORG}/general 已存在"
else
api -X POST -d '{"name":"general","auto_init":true,"private":true}' \
"${BASE_URL}/api/v1/orgs/${ORG}/repos" >/dev/null
echo "已创建仓库 ${ORG}/general"
fi
echo "用 ${USERNAME} 登录 ${BASE_URL} 看首页卡片; 期望按钮指向 ${ORG}/general/issues"
;;
check) check)
python3 "${ROOT}/build.py" --check --quiet python3 "${ROOT}/build.py" --check --quiet
fail=0 fail=0
@@ -100,7 +126,9 @@ check)
curl -fsS "${BASE_URL}/" -o "${html}" curl -fsS "${BASE_URL}/" -o "${html}"
grep -q "先搜索,再提问" "${html}" && ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容" grep -q "先搜索,再提问" "${html}" && ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
grep -q "assets/tjhlp/ask-guide.html" "${html}" && ok "导航栏/首页已指向课程提问指南" || bad "没找到提问指南链接" grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
ok "导航栏/首页已指向官网提问指南(/Website/qa/ask/)" ||
bad "没找到官网提问指南链接(页面还是旧模板? 模板改动要重启 gitea 才生效)"
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${html}" && ! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${html}" &&
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案" ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
! grep -qi "powered by" "${html}" && ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by" ! grep -qi "powered by" "${html}" && ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
@@ -108,24 +136,58 @@ check)
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${html}" && grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${html}" &&
ok "meta description 已替换" || bad "meta description 未替换" ok "meta description 已替换" || bad "meta description 未替换"
curl -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" && # 站内提问指南页已按决定删除(提问指南只在官网保留一份)
ok "custom/public 静态页可访问" || bad "提问指南静态页 404" ! curl -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" 2>/dev/null &&
ok "平台内提问指南页已删除" || bad "平台内还留着 ask-guide.html"
# --- 与课程官网的联动 ------------------------------------------------- # --- 与课程官网的联动 -------------------------------------------------
grep -q "https://cpp.tongji.sh/Website/" "${html}" && grep -q "https://cpp.tongji.sh/Website/" "${html}" &&
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接" ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
grep -q "https://cpp.tongji.sh/Website/ask-question/" "${html}" && grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
ok "首页已链接官网《学会提问》" || bad "首页没有《学会提问》链接" ok "首页已链接官网提问指南" || bad "首页没有官网提问指南链接"
guide="$(mktemp)" ! grep -q "Website/ask-question/\|Website/faq/\|Website/contact\"" "${html}" &&
curl -fsS "${BASE_URL}/assets/tjhlp/ask-guide.html" -o "${guide}" ok "没有指向官网已迁移/失效的旧地址" ||
grep -q "Website/ask-question/" "${guide}" && ok "站内提问指南已回链官网" || bad "站内提问指南没有官网链接" bad "仍有旧地址(ask-question / faq / contact 无 .html)"
rm -f "${guide}"
! grep -rq "example.com" "${ROOT}/../issue-templates/" && ! grep -rq "example.com" "${ROOT}/../issue-templates/" &&
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com" ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" && ! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" &&
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」" ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
# --- 登录页 -----------------------------------------------------------
login="$(mktemp)"
curl -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/user/login" -o "${login}"
grep -q "管理员登录" "${login}" &&
ok "登录页有独立的「管理员登录」卡片" || bad "登录页缺少管理员登录卡片"
! grep -q "webauthn-error\|signin-passkey" "${login}" &&
ok "登录页已无空的通行密钥(WebAuthn)方框" || bad "登录页仍有通行密钥区块"
grep -q 'id="external-login-navigator"' "${login}" ||
echo " (提示: 预览未配置认证源, 登录页不显示统一身份认证按钮; 见 customization/README.md 3.4)"
rm -f "${login}"
# --- 首页(登录后)的「本学期答疑入口」卡片 -----------------------------
# 预览里没有管理员/学期组织时会跳过(只提示), 不算失败。
cj="$(mktemp)"
dash="$(mktemp)"
trap 'rm -f "${html}" "${cj}" "${dash}"' EXIT
curl -fsS -c "${cj}" -b "${cj}" -X POST \
--data-urlencode "user_name=${PREVIEW_ADMIN_USER:-previewadmin}" \
--data-urlencode "password=${PREVIEW_ADMIN_PASSWORD:-previewadmin123}" \
"${BASE_URL}/user/login" -o /dev/null || true
curl -fsS -b "${cj}" "${BASE_URL}/" -o "${dash}" || true
if ! grep -q 'class="page-content dashboard' "${dash}"; then
echo " (提示: 预览里没有可登录的 previewadmin; 跑 ./preview.sh admin 后再检查登录后页面)"
elif grep -q "本学期答疑入口" "${dash}"; then
ok "首页(登录后)有「本学期答疑入口」卡片"
grep -q "/tjhlp-[0-9]\{5\}/general/issues" "${dash}" &&
ok "卡片按钮指向 <学期组织>/general/issues" ||
bad "卡片按钮链接不是 <学期组织>/general/issues"
grep -q "min-height:33vh" "${dash}" &&
ok "卡片高度约 1/3 屏(33vh)" || bad "卡片没有 33vh 高度"
else
echo " (提示: 当前登录用户不属于任何学期组织 => 卡片不显示; 跑 ./preview.sh semester 造一个)"
fi
[ "${fail}" = 0 ] && echo "全部检查通过" || echo "存在检查未通过项" [ "${fail}" = 0 ] && echo "全部检查通过" || echo "存在检查未通过项"
exit "${fail}" exit "${fail}"
;; ;;
+2
View File
@@ -7,3 +7,5 @@
options/locale/locale_zh-CN.json options/locale/locale_zh-CN.json
templates/home.tmpl templates/home.tmpl
templates/base/head_navbar.tmpl templates/base/head_navbar.tmpl
templates/user/auth/signin.tmpl
templates/user/dashboard/dashboard.tmpl
@@ -0,0 +1,10 @@
{{template "base/head" .}}
<div role="main" aria-label="{{.Title}}" class="page-content user signin{{if .LinkAccountMode}} icon{{end}}">
<div class="ui middle very relaxed page grid">
{{/* these styles are quite tricky and should also apply to the signup and link_account pages */}}
<div class="column tw-flex tw-flex-col tw-gap-4 tw-max-w-2xl tw-m-auto">
{{template "user/auth/signin_inner" .}}
</div>
</div>
</div>
{{template "base/footer" .}}
@@ -0,0 +1,17 @@
{{template "base/head" .}}
<div role="main" aria-label="{{.Title}}" class="page-content dashboard feeds">
{{template "user/dashboard/navbar" .}}
<div class="ui container flex-container">
<div class="flex-container-main">
{{template "base/alert" .}}
{{template "user/heatmap" .}}
{{if .Page.Paginater.TotalPages}}
{{template "user/dashboard/feeds" .}}
{{else}}
{{template "user/dashboard/guide" .}}
{{end}}
</div>
{{template "user/dashboard/repolist" .}}
</div>
</div>
{{template "base/footer" .}}
+9 -3
View File
@@ -68,9 +68,15 @@
Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑 Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑
平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样 平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样
流程重拍、**文件名不变**地替换, 这样正文不用改。 流程重拍、**文件名不变**地替换, 这样正文不用改。
11. **内容重复**:官网《学会提问》与平台内 `/assets/tjhlp/ask-guide.html` 有重叠。平台侧 11. **内容重复(已在平台侧处理完)**:官网提问指南与平台内的副本曾有重叠。2026-09 起
已把官网定为权威版本(站内页顶部注明"以官网为准"并给出链接), 官网页不必反向复制平台 **提问指南只在官网保留一份**(`/Website/qa/ask/`), 平台内的
操作细节, 链接到 `/faq/gitea/` 即可。 `/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. 建议改动(可直接套用)
+14
View File
@@ -28,6 +28,20 @@ POSTGRES_DATA_DIR=/srv/pgdata
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
GITEA_CUSTOM_DIR=../customization/custom GITEA_CUSTOM_DIR=../customization/custom
# -----------------------------------------------------------------------------
# 容器出站代理(见 compose.yaml 同段落注释 / README 陷阱 6)
# 默认: compose.yaml 里显式写成空值, 即容器内【不用代理】。这不是省事, 是有意的:
# * compose 会把「运行 compose 的 shell」里的 http_proxy 自动注入容器, 而本机登录
# shell 里是 127.0.0.1:7890 —— 那个地址在容器里是容器自己, 一旦被注入, Gitea
# 启动时 OIDC discovery 就失败, 统一身份认证登录 404; 显式给空值能挡住注入。
# * 容器【直连外网是通的】(实测 dl.gitea.com / api.github.com / codeload 都能直连),
# 平台功能相关的出站(OIDC)也在内网直连, 所以不需要代理。
# 将来若确实要给容器配代理, 必须是【容器可达】的地址(别写 127.0.0.1, 那是容器自己):
# -----------------------------------------------------------------------------
#GITEA_HTTP_PROXY=https://cpp.tongji.sh:7890
#GITEA_HTTPS_PROXY=https://cpp.tongji.sh:7890
#GITEA_NO_PROXY=localhost,127.0.0.1,::1,10.80.42.185,.local,.internal
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
# 版本(锁定, 便于回滚) # 版本(锁定, 便于回滚)
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
+135 -1
View File
@@ -35,6 +35,7 @@
| **恢复**(含演练) | §6 | `sudo ./scripts/restore.sh <时间戳> --apply` | | **恢复**(含演练) | §6 | `sudo ./scripts/restore.sh <时间戳> --apply` |
| **升级** Gitea / PostgreSQL | §7 | 备份 → 改 `.env` → `up -d` | | **升级** Gitea / PostgreSQL | §7 | 备份 → 改 `.env` → `up -d` |
| 改首页 / 中文术语 / 去 Gitea 化 | [`../customization/README.md`](../customization/README.md) | `python3 customization/build.py` → `docker compose restart gitea` | | 改首页 / 中文术语 / 去 Gitea 化 | [`../customization/README.md`](../customization/README.md) | `python3 customization/build.py` → `docker compose restart gitea` |
| main 推送后自动部署(方案) | [`ci-cd.md`](ci-cd.md) | Gitea Actions + 宿主 act_runner(host 模式) |
| 出问题了 | §12 | — | | 出问题了 | §12 | — |
| 退回二进制部署 | §9 | `docker compose down && sudo systemctl start gitea` | | 退回二进制部署 | §9 | `docker compose down && sudo systemctl start gitea` |
@@ -145,6 +146,99 @@
> curl -sS --noproxy '*' http://127.0.0.1:2080/api/healthz > curl -sS --noproxy '*' http://127.0.0.1:2080/api/healthz
> ``` > ```
> **⚠️ 6. compose 会把 shell 的 `http_proxy` 注入容器 —— 会让 OIDC 登录整条 404。**
> `docker compose up` 会自动把**运行它的那个 shell** 里的 `HTTP_PROXY`/`HTTPS_PROXY`/
> `NO_PROXY`(大小写都算)注入容器。本机登录 shell 里是
> `http_proxy=http://localhost:7890`,而 **`localhost`/`127.0.0.1` 在容器里指向容器自己**,
> 于是 Gitea 启动时拉 OIDC discovery 失败:
> ```text
> initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
> Error: Failed to initialize OpenID Connect Provider ... proxyconnect tcp:
> dial tcp 127.0.0.1:7890: connect: connection refused
> ```
> 认证源注册不上 → 登录页的按钮还在(它来自数据库), 但点下去
> `/QA/user/oauth2/...` 返回 **404**, 统一身份认证**完全无法登录**。
> 这个坑很隐蔽: 容器是健康的、健康检查 `200`、登录页 `200`, 只有真正点登录才炸。
>
> `compose.yaml` 现在**显式**给出这几个变量、且默认**空值**(= 容器内不用代理),
> 显式赋值可以挡住自动注入。**默认不用代理的依据**(2026-09-13 实测):
> * 容器**直连外网是通的**: `dl.gitea.com`、`api.github.com`、`codeload.github.com`
> 在容器里直接 curl 分别是 `200/200/301`(`github.com` 主站直连会超时, 但平台不依赖它);
> * 与功能相关的出站只有 OIDC, 目标是 `10.80.42.185`, 容器内直连即 `200`;
> * 宿主 `7890` 那个代理是 **ssh 转发的开发用代理**, `ss -ltn` 显示只监听
> `127.0.0.1:7890`/`[::1]:7890` —— 在容器里 `127.0.0.1` 是容器自己,
> `10.80.42.185:7890` 也不可达(实测 `curl -x` 直接 `Could not connect`),
> 所以这个代理配进容器只会让出站先绕一圈再失败。
>
> 将来真要给容器配代理, 必须是**容器可达**的地址(把隧道绑到 LAN 口, 或让容器用
> host 网络), 再在 `.env` 里给 `GITEA_HTTP_PROXY`(见 `.env.example`)。
> **每次 `up -d` 后建议验一次** OIDC 入口是否还通:
> ```bash
> curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \
> 'http://127.0.0.1:2080/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81'
> # 期望: 307 + Location: https://cpp.tongji.sh/oidc/auth?... (404 = 认证源没注册上)
> ```
>
> **⚠️ 7. 全新克隆 + compose: docker 会以 root 创建不存在的挂载源目录。**
> `compose.yaml` 把 `customization/custom/{options,public,templates}` 逐个挂进容器。
> 其中 `options/` 里只有生成出来的 `locale_zh-CN.json`, 而它是 gitignore 的 —— 于是
> 全新克隆里这个目录不存在, **docker 会以 root 创建它**, 之后普通用户跑
> `customization/build.py` 就写不进去:
> ```
> PermissionError: [Errno 13] Permission denied: .../custom/options/locale
> ```
> 后果不是报错那么明显: 语言文件生成失败 → 中文界面退回上游文案(「工单」又回来了),
> 而首页/登录页看起来一切正常。2026-09-13 第一次把生产切到部署克隆(CI 用的那份)时踩到。
>
> 现在有两道防线: ①仓库里 `customization/custom/options/.gitkeep` 让目录随 checkout 就存在
> 且属于当前用户; ②`deploy/scripts/auto-deploy.sh` 在部署前检查三个目录存在且**可写**,
> 不满足就明确报错。若已经中招:
> ```bash
> sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可
> ```
>
> **⚠️ 8. `docker.sock` 怎么挂:`docker_host: "-"` 与"job 自己申报"是配套的一对。**
> 默认行为是 act_runner 把 docker daemon socket **自动**挂进 job 容器 —— 等于这个 runner 上的
> **每个** job 都白拿 docker(= root 等价)。现在把这份能力收窄成"要用 docker 的 job 自己申报":
> ```yaml
> # deploy/runner/config.yaml —— runner 侧: 不自动挂, 并给申报加白名单
> container:
> docker_host: "-" # 自动找 daemon, 但不挂进 job 容器
> valid_volumes: [...] # job 申报的挂载必须在这个表里
> ```
> ```yaml
> # .gitea/workflows/deploy.yml —— job 侧: 只给需要它的那个 job
> container:
> volumes:
> - /var/run/docker.sock:/var/run/docker.sock
> ```
> ⚠️ **两者必须成对**: 只写 `volumes` 而没有 `docker_host: "-"`, 就会和自动挂载撞成
> ```
> failed to create container: 'Duplicate mount point: /var/run/docker.sock'
> ```
> (2026-09-13 用 `act_runner exec` 预演时第一次踩到。注意 `exec` 有自己的
> `--container-daemon-socket` 默认值、**不读**配置里的 `docker_host`, 所以用 exec 预演时
> 这个错会一直出现 —— 它验证不了这一项。)
>
> **⚠️ 10. `valid_volumes` 会静默丢掉挂载。**
> job 申报的 `container.volumes`(以及全局 `options` 里的 `--volume`)都必须出现在
> `container.valid_volumes` 里, 否则 act_runner 只打一行
> `... is not a valid volume, will be ignored` 就把它丢掉, **job 照常往下跑** —— 现象是容器里
> 少了个目录, 而不是报错。2026-09-21 就因此让部署 job 的
> `cd /home/ymy/deploy/tjhlp-gitea` 失败。排查两行命令:
> ```bash
> docker exec gitea-runner sed -n '/valid_volumes/,+6p' /config/config.yaml
> docker inspect $(docker ps -q --filter name=GITEA-ACTIONS) \
> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
> ```
>
> **⚠️ 9. 宿主 `/usr/bin/python3` 是 3.6, 别让它排到 PATH 前面。**
> `customization/build.py` 用了 `from __future__ import annotations`, 需要 ≥3.7。
> 宿主上正确的解释器是 `~/.local/bin/python3`(3.14), 但 `/usr/bin/python3` 是 Rocky 8 的
> 3.6 —— 只要 PATH 被改成 `/usr/bin` 优先, 就会看到
> `SyntaxError: future feature annotations is not defined`, 而且**语言文件静默地不再更新**。
> `auto-deploy.sh` 现在自己挑一个 ≥3.7 的解释器(并用它跑 build.py), 不依赖 PATH 顺序。
--- ---
## 3. 本机关键事实 ## 3. 本机关键事实
@@ -722,6 +816,8 @@ if SecretKey == "" {
| `docker build` 报 `lookup auth.docker.io ... i/o timeout` | §4.3 | 先 `docker pull` 基础镜像 | | `docker build` 报 `lookup auth.docker.io ... i/o timeout` | §4.3 | 先 `docker pull` 基础镜像 |
| `docker pull` 报 `i/o timeout` | §4.3 | 代理 drop-in 没生效, `systemctl show docker -p Environment` | | `docker pull` 报 `i/o timeout` | §4.3 | 代理 drop-in 没生效, `systemctl show docker -p Environment` |
| 容器 healthy 但站点 503 | `docker compose logs gitea` | 多为 `.env` 里 DB 密码与既有数据不一致 | | 容器 healthy 但站点 503 | `docker compose logs gitea` | 多为 `.env` 里 DB 密码与既有数据不一致 |
| CI 部署"成功"但页面还是旧模板 / 部署回滚 | `ci-cd.md` §5.2 | `custom/` 变了却没重启容器(或挂载源目录被换过 inode), 见该节说明 |
| `/QA/assets/...` 下自己放的静态文件 404 | — | 挂载的 `custom/public` 目录被删除重建过, `docker compose restart gitea` 重新挂载 |
--- ---
@@ -789,7 +885,7 @@ systemctl start gitea`(§9)。
| 配置 | 迁移前 | 现在 | 原因 | | 配置 | 迁移前 | 现在 | 原因 |
|---|---|---|---| |---|---|---|---|
| `log.MODE` | `file` | `console` | 日志进 stdout, 用 `docker compose logs` 收集 | | `log.MODE` | `file` | `console` | 日志进 stdout, 用 `docker compose logs` 收集 |
| `server.DISABLE_SSH` | `false` | `true` | 实测 `/home/git/.ssh` 不存在, SSH 从未使用; 避免暴露无法工作的克隆地址 | | `server.DISABLE_SSH` | `false` | `true` | 只提供 HTTP 克隆地址; 见下面的「如需启用 SSH 克隆」 |
| `server.DOMAIN` | `localhost` | 实际主机/IP | `localhost` 会生成错误的克隆地址; `ROOT_URL` 已显式指定, 此项属修正 | | `server.DOMAIN` | `localhost` | 实际主机/IP | `localhost` 会生成错误的克隆地址; `ROOT_URL` 已显式指定, 此项属修正 |
| `security.ALLOWED_HOST_LIST` | `[security]`(**正确**) | **保持 `[security]`** | 1.27 的规范位置就是 `[security]`; `[webhook]` 是 v28.0.0 将移除的 deprecated fallback | | `security.ALLOWED_HOST_LIST` | `[security]`(**正确**) | **保持 `[security]`** | 1.27 的规范位置就是 `[security]`; `[webhook]` 是 v28.0.0 将移除的 deprecated fallback |
| `server.HTTP_ADDR` | `0.0.0.0:2080` | 容器内 `0.0.0.0`, 宿主只发布 `127.0.0.1:2080` | 保持 Apache 反代路径不变, 同时消除直连暴露面 | | `server.HTTP_ADDR` | `0.0.0.0:2080` | 容器内 `0.0.0.0`, 宿主只发布 `127.0.0.1:2080` | 保持 Apache 反代路径不变, 同时消除直连暴露面 |
@@ -798,6 +894,44 @@ systemctl start gitea`(§9)。
其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、 其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、
`PASSWORD_HASH_ALGO=pbkdf2`、`OFFLINE_MODE`、webhook TLS 等)均按原值 1:1 保留。 `PASSWORD_HASH_ALGO=pbkdf2`、`OFFLINE_MODE`、webhook TLS 等)均按原值 1:1 保留。
#### 如需启用 SSH 克隆(可选, 默认关闭)
关闭后界面上所有克隆地址都是 HTTP, 加公钥时也会提示"SSH 目前已禁用, 这些密钥仅用于提交
签名验证"。实测现状(2026-09-23):
| 事实 | 值 |
|---|---|
| 镜像自带 sshd | **有**: s6 服务 `/etc/s6/openssh`, 容器内**已在 `0.0.0.0:22` 上监听**(只是没发布端口) |
| 发布到宿主 | 没有 —— `docker port gitea` 只有 `3000/tcp -> 127.0.0.1:2080`, 所以外部连不上 |
| git 用户家目录 | `/data/git`(不是旧版镜像的 `/home/git`) |
| 授权文件 | `/data/git/.ssh/authorized_keys`, **由 Gitea 维护**(形如 `command="… gitea serv key-N"`), 所以加过公钥的账号启用后立刻可用, 不用重加 |
| host key | `/data/ssh/ssh_host_{ed25519,rsa,ecdsa}_key`, 在 `/data` 持久卷里(迁移会一起走) |
| 认证策略 | `PasswordAuthentication no` / `AllowUsers git` / `PermitRootLogin no` / `AllowTcpForwarding,AllowAgentForwarding no` —— 只能公钥 |
| 宿主 22 | 被宿主自己的 OpenSSH 占着(`0.0.0.0:22`), 所以 Gitea 得换端口 |
要启用得同时改三处, 少一处就会出现 `ssh://git@localhost:22/...` 这种没用的克隆地址
(这正是当初关掉它的原因):
```yaml
GITEA__server__DISABLE_SSH: "false"
GITEA__server__SSH_DOMAIN: ${GITEA_DOMAIN} # 对外主机; 默认值是 localhost
GITEA__server__SSH_PORT: "2222" # 展示在克隆地址里的端口
ports:
- "0.0.0.0:2222:22" # 宿主 2222 -> 容器 sshd 的 22
```
然后 `docker compose up -d gitea`(端口变了要重建容器), 验证:
```bash
ssh -T -p 2222 [email protected] # 期望: Hi <用户名>! You've successfully authenticated, ...
```
**代价**: 绕过 Apache 多开一个对外的口子(当前 firewalld 未运行 = 校内可达)、多一个攻击面、
`SSH_DOMAIN`/`SSH_PORT` 必须和实际一致、非 22 端口对使用者不友好。**好处**: 免密推送(私钥
不出本机), 而当前平台是纯 HTTP —— HTTP 推送的账号密码/token 是 base64 明文过网。
只需要给自己和几个助教免密的话, 用 HTTP + Personal Access Token +
`git config --global credential.helper 'cache --timeout=604800'` 更省事, 不必动服务器。
**迁移中发现并处理的既有问题**: **迁移中发现并处理的既有问题**:
| # | 问题 | 证据 | 处理 | | # | 问题 | 证据 | 处理 |
+603
View File
@@ -0,0 +1,603 @@
# CI/CD:main 自动部署(Gitea Actions 方案)
> **状态:已落地并本地验证通过(2026-09-13),只差一次 `git push`。**
> runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器)
> 已在本机预演通过;推送 `main` 后第一次 CI 运行即接管。**全程不需要 root。**
>
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
> 当前进度与剩余动作见 §0.1。
> 相关文档:[deploy/README.md](README.md)(部署与陷阱,含本次踩到的 3 个坑)、
> [customization/README.md](../customization/README.md)(定制机制与预览)。
---
## 0. 目标
`course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交:
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
### 0.1 落地现状与剩余动作(更新到 2026-09-22)
**CI/CD 已上线跑通。** `action_run` 表里共 5 次运行:前几次是打通路上的跳过/失败,最新一次
(HEAD `9954700`)`status=1`(=Success),`deploy/.state/last-deployed` = `9954700` —— 生产
就是 CI 部署的版本。
| 项 | 证据 |
|---|---|
| 部署克隆 `/home/ymy/deploy/tjhlp-gitea`(`origin` = 本机裸仓库,免凭据) | `git remote -v`;`deploy/.env` 600 |
| runner 已注册 | `action_runner`:`tjhlp-gitea-1 / v0.6.1 / ["self-hosted"]` |
| 生产由 CI 部署 | `last-deployed` = HEAD 的 SHA;`action_run` 最新一次 `status=1` |
| job 容器里工具齐全 | `act_runner exec` 预演:`Python 3.10.12 / git 2.55 / docker server 29.8.0 / compose v5.5.1` |
2026-09-21 打通时踩的三个坑(对应当天几次红色的运行):
1. **`container.valid_volumes` 为空表时,挂载会被静默丢弃**(只打一行
`... is not a valid volume, will be ignored`)→ job 容器里没有部署克隆,第一步
`cd /home/ymy/deploy/tjhlp-gitea` 就失败。修法:把要挂的路径列进白名单。
2. **部署克隆的 `origin` 是宿主上的本地裸库**(`/srv/gitea/...`),job 容器里没有它 →
`git fetch` 报 "does not appear to be a git repository"。修法:把 `/srv/gitea` 只读挂进去。
3. **workflow 的 step 之间不共享工作目录**,第二步要自己 `cd` 过去(`actions/checkout` 那种
"代码在当前目录"的心智模型在这里不成立)。
2026-09-22 本轮改动:**把宿主能力从"runner 全局发给每个 job"收窄成"deploy job 自己申报"**:
- `container.docker_host: "-"` → 不再自动把 docker socket 挂进 job 容器;
- 删掉 `container.options` 里的全局挂载;
- 五项挂载(部署克隆、`/srv/gitea`、socket、docker CLI、compose 插件)改为在
`.gitea/workflows/deploy.yml` 的 `container.volumes` 里申报,并全部列进
`container.valid_volumes` 白名单。
效果:**将来加的 PR 检查/测试 job 默认是裸容器**——没有宿主路径,也申报不了白名单之外的卷
(本机实测:不申报任何挂载的 job 看不到 `/home/ymy/deploy` 与 `/srv/gitea`)。socket 那一项
在真实调度路径上的确认方式与失败模式见 §9,其余残留见 §7.2。
剩余动作:
1. 本轮改动**要等一次 push 才能端到端验证**(判据与回退方式见 §9 第 2 条)。
2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9);确认前不要把仓库
开放给不可信贡献者。
3. 给 `main` 加分支保护(§4.4)。
---
## 1. 现状与约束 **[实测]**
| 项 | 实测值 | 对方案的影响 |
|---|---|---|
| Gitea | 1.27.3;Actions 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` | 不用改配置就能用 |
| 已注册 runner | 方案制定时**无**(现已注册,见 §0.1) | 要自己起一个 |
| `act_runner` 镜像 | `docker pull gitea/act_runner:latest` 成功:**arm64, v0.6.1, 69.3MB** | runner 用容器跑,**不需要 root** |
| job 镜像 | `docker.gitea.com/runner-images:ubuntu-22.04`(Gitea 官方, arm64 可用)、`catthehacker/ubuntu:act-22.04`(arm64, 压缩约 512MB)、`node:20-bookworm-slim`、`rockylinux:8` 的 manifest 都能取到 | 有现成镜像可跑容器模式 job |
| 宿主出网 | 国内直连 `200`;境外经代理 `200`(`https://dl.gitea.com/...`、`https://github.com` 经 `127.0.0.1:7890` 均 `200`) | 正常联网,不是离线环境 |
| 容器出网 | 容器内直连:`dl.gitea.com` `200`、`api.github.com` `200`、`codeload.github.com` `301`;**`github.com` 主站直连 12s 超时** | `uses: actions/checkout` 这类动作走 codeload/api 通常可以;主站要通就得给镜像或 `github_mirror` |
| docker daemon 代理 | `/etc/systemd/system/docker.service.d/http-proxy.conf` 里 `HTTP(S)_PROXY=http://127.0.0.1:7890` | 镜像拉取走代理,正常 |
| `ymy` 的组 | `ymy, wheel, git(982), docker(980)` | 容器方案不需要 sudo;host 模式才需要 |
| 裸仓库 | `/srv/gitea/git/repositories/course-team/tjhlp-gitea.git`,`drwxr-xr-x git:git`,`git ls-remote` 通(需 `safe.directory`,见 §4.1) | CI 可以**免凭据**取代码 |
| 现成积木 | `deploy/scripts/{verify,backup,restore}.sh`、`customization/build.py`、`preview.sh check` | 直接复用 |
---
## 2. 方案总览
### 2.1 架构
```text
开发者 push main
│
▼
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
▲ │ 拉起 job 容器
│ 日志/状态显示在仓库 Actions 标签 ▼
└──────────────────── job 容器(network: host;宿主能力由 job 自己申报)
├─ 挂 docker.sock → 可执行 docker compose
├─ 挂 /home/ymy/deploy(同路径, 部署克隆)+ /srv/gitea(ro, 它的 origin)
└─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
未申报的 job(将来的 PR 检查)拿不到上面任何一项
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
| | **A. 容器(推荐)** | B. 宿主二进制 + host 模式 |
|---|---|---|
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
| 挂载 | 由 deploy job 在 `container.volumes` 里申报(受 runner 的 `valid_volumes` 白名单约束) | 无 |
| 开机自启 | compose 的 `restart: unless-stopped` | systemd |
| 结论 | **默认选它**:不需要 root、标准、日志清晰 | 想少一层容器、且你愿意跑一次 sudo 时选它 |
act_runner v0.6.1 自己的 `generate-config` 输出里明确写了两种 label 写法,两个事实由此确认:
```text
# Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
labels:
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
container:
# Could be host, bridge or the name of a custom network.
network: ""
```
即 **`:host` 支持**(备选 B 可用)、**`container.network: host` 支持**(方案 A 里让 job 容器
能和宿主共用回环,`verify.sh` 里 `127.0.0.1:2080` 的检查才继续有效)。
### 2.3 触发与门禁
- 触发:`push` 到 `main`,外加 `workflow_dispatch`(落地初期先只手动触发);
- 跳过:提交信息含 `[skip deploy]` 不部署(与 Gitea 自带的 `[skip ci]` 同风格);
- 串行:workflow 的 `concurrency` + 脚本里的 `flock` 双保险;
- 只认 `main`:job 级 `if` 卡死分支,PR/其它分支即使跑工作流也不碰生产。
---
## 3. 组件清单
| 组件 | 位置 | 谁维护 |
|---|---|---|
| 部署克隆 | `/home/ymy/deploy/tjhlp-gitea` | 本方案新建(§4.1) |
| 部署凭据 | `deploy/.env`(`chmod 600`,已 gitignore) | 从现有部署复制 |
| 部署状态 | `deploy/.state/last-deployed`(上次成功的 SHA) | 脚本写,加进 `.gitignore` |
| runner | `deploy/runner/compose.yaml` + `deploy/runner/config.yaml` + `deploy/runner/data/`(gitignore) | 新增到仓库 |
| 工作流 | `.gitea/workflows/deploy.yml` | 新增到仓库(§5.1) |
| 部署脚本 | `deploy/scripts/auto-deploy.sh` | 新增到仓库(§5.2) |
| 定制断言 | `customization/check.sh <base-url>` | 新增到仓库(§5.3) |
---
## 4. 落地步骤
### 4.1 部署克隆(不需要 root)
```bash
# 让 ymy 能读 Gitea 的裸仓库。
# ★ 实测: git -c safe.directory=... 对本机 git 无效, 必须写进配置文件才生效。
git config --global --add safe.directory \
/srv/gitea/git/repositories/course-team/tjhlp-gitea.git
# 从裸仓库克隆: origin 就指向本机裸仓库, CI 全程不需要任何 git token
git clone /srv/gitea/git/repositories/course-team/tjhlp-gitea.git \
/home/ymy/deploy/tjhlp-gitea
cd /home/ymy/deploy/tjhlp-gitea
cp /home/ymy/tjhlp-gitea/deploy/.env deploy/.env # 部署密钥, 别提交
chmod 600 deploy/.env
mkdir -p deploy/.state
```
> ⚠️ 从此 `deploy/.env` 有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**,
> dev 克隆那份只服务本地预览;改密钥时两边同步。
>
> ⚠️ 切换后**不要再从 dev 克隆 `up -d`**:compose 项目名同为 `gitea`(同一组容器),但 bind mount
> 的源路径按 compose 文件所在目录解析,两边会互相覆盖。dev 克隆只留开发与预览。
### 4.2 起 runner 并注册(不需要 root)
先在 Gitea 上拿一个**仓库级**注册令牌(API 实测存在:
`POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token`;
也可以在 仓库 → Settings → Actions → Runners 页面点按钮):
```bash
curl -sS -X POST \
-H "Authorization: token <你的 PAT, 需要 repo 权限>" \
"https://cpp.tongji.sh/QA/api/v1/repos/course-team/tjhlp-gitea/actions/runners/registration-token" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])'
```
把令牌写进 `deploy/runner/.env`(gitignore),然后:
```bash
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner
docker compose up -d
docker compose logs -f runner # 看到 "runner registered successfully" 即可
```
仓库 → Settings → Actions → Runners 里应出现 `tjhlp-gitea-1`(Idle)。注册令牌用完即弃:
注册结果存在 `deploy/runner/data/.runner`,之后 runner 用它通信,不会过期。
`deploy/runner/compose.yaml`:
```yaml
name: gitea-runner
services:
runner:
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1 / 可拉取
restart: unless-stopped
environment:
# 这组变量名来自镜像里的 /usr/local/bin/run.sh(实测)
GITEA_INSTANCE_URL: https://cpp.tongji.sh/QA
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?先按 §4.2 拿令牌}
GITEA_RUNNER_NAME: tjhlp-gitea-1
# 不要在 env 里设 GITEA_RUNNER_LABELS: act_runner 会警告
# "Labels from command will be ignored, use labels defined in config file.",
# label 以 config.yaml 为准(实测)
CONFIG_FILE: /config/config.yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
- ./data:/data # 注册凭据 (.runner)
- ./config.yaml:/config/config.yaml:ro
```
`deploy/runner/config.yaml`:
```yaml
log:
level: info
runner:
file: /data/.runner
capacity: 1 # 部署必须串行, 一个 job 一个 job 地跑
timeout: 30m
labels:
# job 跑在容器里; 镜像换成本地已有/更小的亦可(如 catthehacker/ubuntu:act-22.04)
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
container:
network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连
docker_host: "-" # 自动找 daemon, 但【不】把 socket 挂进 job 容器(要用 docker 的 job 自己申报)
valid_volumes: # 允许 job 申报的挂载白名单(glob 匹配挂载源路径; [] = 一个都不许)
- /home/ymy/deploy
- /srv/gitea
- /var/run/docker.sock
- /usr/bin/docker
- /usr/libexec/docker/cli-plugins
# 这里【故意不写】全局 options: 挂载由 deploy job 自己申报, 见 §5.1
force_pull: false # 镜像已有就别每次拉
cache:
enabled: true
```
四处关键点:
- **白名单管两头**:job 申报的 `container.volumes` 和全局 `options` 里的 `--volume` 都要在
`valid_volumes` 里,否则被**静默丢弃**(`... is not a valid volume, will be ignored`),
2026-09-21 实际因此失败;
- **同路径挂载 `/home/ymy/deploy`**:`docker compose` 在 job 容器里把相对挂载解析成绝对路径后
交给宿主 daemon 执行,路径不一致会挂到空目录;
- **`/srv/gitea` 只读**:部署克隆的 `origin` 是这个宿主路径下的裸库,job 容器里没有它就
`git fetch` 不了(2026-09-21 实际踩到);
- **不把 `docker.sock` 写进全局 `options`**:那等于每个 job 都拿到 root。改由 deploy job
自己申报,而 `docker_host: "-"` 保证它不会和"自动挂载"撞成
`Duplicate mount point: /var/run/docker.sock`。
### 4.3 试运行(手动触发)
1. 提交 §5 的文件,workflow 的 `on:` **先只留 `workflow_dispatch`**(没有 runner 时 push 触发
会一直挂在"等待 runner");
2. 仓库 → Actions → deploy → **Run workflow**(选 `main`);
3. 盯日志确认:构建 → `up -d` → 验证全过 → Actions 绿色;
4. 故意推一个坏提交(例如把 `overrides/locale_zh-CN.json` 的键写错)验证**回滚路径**真的生效。
### 4.4 打开自动触发 + 加保护
1. 把 `push: branches: [main]` 加回 workflow;
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**;
3. `deploy/README.md` 的快速索引里已有一行指向本文档。
---
## 5. 流水线内容
### 5.1 `.gitea/workflows/deploy.yml`
刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
```yaml
# main 推送后自动部署到 10.80.42.185/QA。
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
# 详见 deploy/ci-cd.md。
name: deploy
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: deploy-main
cancel-in-progress: false
permissions:
contents: read
jobs:
deploy:
# 只认 main 的 push 或手动触发; 提交信息含 [skip deploy] 则跳过
if: >-
github.event_name == 'workflow_dispatch' ||
(github.ref == 'refs/heads/main' &&
!contains(github.event.head_commit.message, '[skip deploy]'))
runs-on: self-hosted
timeout-minutes: 30
# ★ 宿主能力(docker socket、部署克隆、裸库、docker CLI)由【本 job】申报,而不是由
# runner 全局发给每个 job。runner 侧的 container.valid_volumes 是允许清单:
# 没列进去的挂载会被丢弃,所以这里的每一项都要在 deploy/runner/config.yaml 里有对应项。
# 将来加 PR 检查/测试 workflow 时,那个 job 不申报就什么都拿不到(无 socket = 无 root)。
container:
volumes:
- /home/ymy/deploy:/home/ymy/deploy # 工作目录(auto-deploy.sh 要写 .state)
- /srv/gitea:/srv/gitea:ro # deploy 克隆的 origin(本地裸库)
- /var/run/docker.sock:/var/run/docker.sock # docker compose up -d
- /usr/bin/docker:/usr/bin/docker:ro # 宿主 docker CLI
- /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro # compose 插件
steps:
- name: 同步到目标提交
run: |
set -euo pipefail
cd /home/ymy/deploy/tjhlp-gitea
git fetch --prune origin
# -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
# 若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
git checkout -f --detach "${{ github.sha }}"
git --no-pager log --oneline -1
- name: 构建并部署(失败自动回滚)
run: |
set -euo pipefail
# 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
# 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
cd /home/ymy/deploy/tjhlp-gitea
./deploy/scripts/auto-deploy.sh
```
`container.volumes` 那一块是 2026-09-22 收窄授权的结果:需要宿主能力的只有这一个 job,
所以挂载在它这里申报;runner 侧的 `valid_volumes` 决定哪些申报能被接受。**加新的 workflow
(例如 PR 检查)时不需要、也不要给它申报这些卷** —— 它默认就是裸容器。
**不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本,
省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。
将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理,
或在 runner 的 `config.yaml` 里设置 `github_mirror`(v0.6.1 的配置注释里就是为"特殊网络环境"
准备的),把 `uses:` 的 github 地址替换成镜像。
### 5.2 `deploy/scripts/auto-deploy.sh`
```bash
#!/usr/bin/env bash
# main 自动部署。由 .gitea/workflows/deploy.yml 调用, 也可手工执行:
# ./auto-deploy.sh # 部署当前 checkout
# ./auto-deploy.sh <sha> # 部署指定提交
set -euo pipefail
REPO_DIR=$(cd "$(dirname "$0")/../.." && pwd)
STATE_DIR="${REPO_DIR}/deploy/.state"
STATE_FILE="${STATE_DIR}/last-deployed"
PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}"
# 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export no_proxy='*' NO_PROXY='*'
# 既能在 job 容器里跑, 也能在宿主上跑: 脚本用 pick_python() 自己挑一个 ≥3.7 的解释器
# (宿主 /usr/bin/python3 是 3.6, 见 README 陷阱 9), 不要写死某台机器的 pyenv 路径
mkdir -p "$STATE_DIR"
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
PREV=$(cat "$STATE_FILE" 2>/dev/null || true)
HASH_FILE="${STATE_DIR}/custom-hash" # 上次成功部署时 custom/ 的指纹
exec 9>"${STATE_DIR}/lock" # workflow 的 concurrency 之外再加一道
flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; }
echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})"
cd "$REPO_DIR"
# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面, 都是启动时加载的
custom_hash() {
(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
}
deploy() { # deploy force = 无条件重启(回滚路径用)
python3 customization/build.py # 生成语言文件 + 规范 custom/ 权限(容器用户要能读)
python3 customization/build.py --check # 生成物/权限校验, 不过就中止, 不碰容器
( cd deploy && docker compose up -d ) # 幂等: 只有配置/镜像变化时才重建
# ★ 必须和【上次成功部署的指纹】比, 不能只比 build.py 前后 —— 后者只能发现语言
# 文件变化, 纯模板改动前后一模一样, 于是永远不重启、容器继续用旧模板(详见下方说明)
if [[ -n "${1:-}" || $(custom_hash) != "$(cat "$HASH_FILE" 2>/dev/null)" ]]; then
( cd deploy && docker compose restart gitea )
fi
}
verify() {
( cd deploy && ./scripts/verify.sh ) # 容器健康 + 本机 API + 经 Apache 反代
customization/check.sh "$PUBLIC_URL" # 定制断言: 首页/登录页/OIDC/术语(见 5.3)
}
rollback() {
[[ -z "${PREV}" ]] && { echo "[auto-deploy] 无历史版本可回退, 保持现状"; return 0; }
echo "[auto-deploy] 回滚到 ${PREV}"
git checkout --detach "$PREV"
deploy force || true # 强制重启: 失败那次可能已用新模板重启过容器
verify || true
}
if deploy && verify; then
echo "$TARGET" > "$STATE_FILE"
custom_hash > "$HASH_FILE" # 记下这次成功部署的指纹, 供下次比较
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
else
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
rollback
exit 1 # 让这次 Actions 运行标红, 完整日志留在 UI 里
fi
```
> **为什么非要 `restart`(2026-09-22 踩到的坑)**:模板与语言文件是 Gitea **启动时**加载的,
> 而 `docker compose up -d` 在 compose 配置没变时**不会重建容器**。最早的实现比较的是
> `build.py` 运行前后的指纹——那只会在语言文件被重新生成时才变;**纯模板改动**(改文案、
> 换链接)前后完全一样,于是从不重启,容器继续用旧模板,`check.sh` 断言失败 → 整个部署
> 被判失败并回滚(「提问指南」换地址那个提交就是这样被回滚的)。改成把指纹记在
> `.state/custom-hash` 里、与**上次成功部署**比较后,模板改动会触发重启。
>
> `restart` 还顺带修一个 bind mount 的坑:挂载**源目录**被「删掉再建」(例如某个提交把
> `custom/public/` 下的文件删光了,git 顺手删掉空目录)后,容器里挂的仍是**旧 inode**,
> 看到的是一个空目录——只有重新 start 才会解析到新目录。同一次事故里线上的
> `/QA/assets/tjhlp/ask-guide.html` 就是这么变成 404 的(已在预览上复现并验证 restart 能修)。
> CI 若只更新了文档/脚本(`custom/` 没动),指纹相同则不重启,省掉一次无谓的停机。
落库前的两个小动作:`.gitignore` 加 `deploy/.state/`、`deploy/runner/data/`、
`deploy/runner/.env`;给 `auto-deploy.sh` 加可执行位(`git` 只记可执行位)。
**不做**的事及理由:
- 每次部署不做数据库备份:部署只改代码/配置,DB 不动;且 `deploy/backups/` 是 `root:root`,
CI 以 `ymy` 跑写不进去。版本升级仍走 README §7(带备份);
- 不自动重推 `issue-templates`:运营动作,不该跟代码推送耦合。
### 5.3 新增 `customization/check.sh <base-url>`
`preview.sh check` 里那一串"定制有没有生效"的断言(首页文案、页脚、meta、静态页、官网链接、
不出现「工单」、登录页两张卡、无通行密钥方框)正是部署后要守的东西。落地时把它抽出来共用:
```bash
customization/check.sh http://127.0.0.1:2081 # 预览
customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里调)
```
生产侧再加两条(今天踩过的坑,必须自动化守住):
```bash
# 1) OIDC 认证源注册成功: 必须是 307 跳到统一身份认证; 404 = 认证源没注册上
curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \
"${BASE}/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81"
# 2) 登录页有「管理员登录」卡片且没有 passkey 空方框
curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -c '管理员登录'
```
---
## 6. 失败与回滚
| 失败点 | 行为 |
|---|---|
| `build.py` 报错(overrides 键不存在/占位符改坏/文件不可读) | 立即中止,**不碰容器**,Actions 标红 |
| `docker compose up -d` 失败(配置语法/镜像缺失) | 重试无意义 → 直接回滚 |
| 容器起不来(模板报错、权限 600 之类的 `[F]`) | `verify.sh` 等到 start_period 结束仍非 healthy → 回滚 |
| 验证断言失败(首页文案丢了、OIDC 404、出现「工单」) | 回滚 |
| 回滚也失败 | 脚本打印现场并 `exit 1`;线上仍是坏版本,需要人工介入(`docker compose logs`) |
| runner 掉线 | 推送后 Actions 显示"等待 runner",**不会**部署、也不影响线上;`docker compose up -d` 恢复 |
回滚 = `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码与挂载文件;
数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以几十秒内完成。
---
## 7. 安全
### 7.1 收窄后的边界(2026-09-22 起)
runner 不再把宿主能力全局发给每个 job:
- `container.docker_host: "-"`:**不**把 docker socket 自动挂进 job 容器;
- 需要宿主能力的是 **deploy job 自己**,它在 `container.volumes` 里申报五项挂载;
- `container.valid_volumes` 是允许清单:申报了但不在表里的卷会被**丢弃**(不是报错),
所以这个 runner 上的任何 job 都挂不上 `/`、`/etc`、`~/.ssh` 之类。
也就是说,"能 root 宿主"从"这个 runner 上的**所有** job"收窄成了"**deploy job** 加上白名单
里那五项"。将来加 PR 检查/测试 workflow 时,那些 job 默认是裸容器(实测:不申报任何挂载的
job 看不到 `/home/ymy/deploy`、`/srv/gitea`)。
### 7.2 仍然存在的残留(别当成"已经隔离了")
1. **能 push workflow 的人 = 能 root 宿主。** job 容器里跑的是仓库里的脚本,而 deploy job
必须有 socket;`main` 的分支保护才是这条的实际控制点。
⚠️ 另外 v0.6.1 **不会**剥离 job 自己申报的逃逸类 `container.options`(如 `--privileged`):
这是 runner 3.x 才有的行为(3.x 文档写明"会剥离并告警",v0.6.1 的 `generate-config` 里
没有这类说明)。所以**升级 runner 到 3.x 值得排期**——镜像 `gitea/runner:3` 已经存在,
配置键(`valid_volumes`/`docker_host`/`container.network`)也是同一套。
2. **`container.network: host` 是 runner 级设置**,收窄不到单个 job:这个 runner 上的每个
job 都共享宿主网络,因此能访问宿主回环上的服务(例如 `127.0.0.1:2080` 的 Gitea)。
要收窄它,得把 `--network host` 挪到 deploy job 的 `container.options`,并把 `verify.sh`
的回环检查改成"连不上就跳过、只认公网 URL"——留作后续。
3. **fork PR 的策略仍未确认**(§9):若 fork PR 能不经批准直接跑 workflow,等于把宿主 root
交给外部 PR;确认之前不要把仓库开放给不可信贡献者。
4. `[skip deploy]`、`if:` 是防误操作,不是安全边界。
### 7.3 其余
- runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root。
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃。
- `gitea/act_runner` 镜像来自 Docker Hub 官方组织仓库;落地时记录 tag/digest(升级方式同 README)。
---
## 8. 日常操作
```bash
# 手动部署当前 main(不依赖 Actions/runner)
/home/ymy/deploy/tjhlp-gitea/deploy/scripts/auto-deploy.sh
# 回滚到指定提交
cd /home/ymy/deploy/tjhlp-gitea && git checkout --detach <sha> && ./deploy/scripts/auto-deploy.sh
# runner 启停 / 看日志
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
docker compose stop runner && docker compose start runner
# ★ 改了 deploy/runner/config.yaml 之后【必须重启 runner】才生效
# (runner 只在启动时读一次配置; 只 `up -d` 不会重建容器)
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose restart runner
# ⚠️ 别让 deploy job 自己去重启 runner: 那等于掐断正在跑的这个 job
# (重启日志里会出现 "cancelled in progress jobs during shutdown")。
# 平台日志(部署后排查)
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
# 每次运行的完整日志在 仓库 → Actions 里
```
---
## 9. 尚未验证的点(诚实清单)
**已经被真实运行确认的**(2026-09-21,共 5 次运行、最新一次成功):
- Gitea 1.27 的调度、日志回传、`concurrency`、`timeout-minutes`、`permissions`、job 级
`if` + `contains(github.event.head_commit.message, ...)`、`github.sha` 都按预期工作;
- job 镜像里有 `git 2.55` / `Python 3.10` / docker CLI;`container.network: host` 下回环与
`10.80.42.185/QA` 都通;`docker compose` 可用;
- runner 配置里的 `container.valid_volumes` 会被**真实调度路径**采纳(09-21 那次失败正是
空白名单把挂载丢掉导致的)。
**仍然未知:**
1. **fork PR 的 workflow 审批行为**(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.2
第 3 条处理。
2. **本轮收窄授权(2026-09-22)的端到端效果**:`docker_host: "-"` + job 自己申报
`container.volumes` 这条路径,`act_runner exec` 验证不了——exec 有自己的
`--container-daemon-socket` 默认值、也不读配置里的 `valid_volumes`(实测:exec 里未授权
路径照样挂上、裸 job 照样有 socket),只能靠一次真实 push。判据:
- **成功**:运行变绿 + `deploy/.state/last-deployed` = 本次 SHA;
- **失败**:部署 job 在第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就报错、**线上不受影响**
(挂载没挂上 = 什么都还没做)→ 说明 `container.volumes` 没被采纳,`git revert` 回退到
"全局 options + 白名单"的旧形态即可。
- 想在**生产路径**上验证"裸 job 真的连 socket 也没有",需要临时加一个
`on: workflow_dispatch` 的探针 workflow(本机只验证了"没有宿主路径"这一半 ✓)。
3. **Actions 日志保留与体积**:`[actions] LOG_RETENTION_DAYS`(默认 365)与存储位置。
4. **Gitea 是否支持"环境审批"**:若有 deployments/environments 的审批,可作为"自动部署但
上线要点一下"的中间档。
---
## 10. 备选方案
| 方案 | 何时选 | 代价 |
|---|---|---|
| **B. 宿主二进制 + host 模式** | 不想给 job 容器挂 docker.sock / 不想维护 job 镜像 | 需要一次 sudo 装 systemd 单元;label 用 `self-hosted:host`(v0.6.1 配置里确认支持) |
| **cron 轮询 + `auto-deploy.sh`** | fork PR 策略不可控,或不想让仓库里的代码在宿主上执行 | 延迟 ≤60s;无 UI/日志,只有落盘日志 |
| **纯手工** | 推送频率低、每次都想人工确认 | 就是现在这样 |
cron 版的触发部分(其余复用 §5.2 的脚本):
```cron
# crontab -e (ymy)
* * * * * cd /home/ymy/deploy/tjhlp-gitea && git fetch -q origin main && \
[ "$(git rev-parse origin/main)" != "$(cat deploy/.state/last-deployed 2>/dev/null)" ] && \
./deploy/scripts/auto-deploy.sh "$(git rev-parse origin/main)" >> deploy/.state/cron.log 2>&1
```
---
## 11. 落地顺序(一句话版)
```text
4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch
手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护
```
+41 -3
View File
@@ -92,6 +92,14 @@ services:
GITEA__other__SHOW_FOOTER_POWERED_BY: "false" GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false" GITEA__other__SHOW_FOOTER_VERSION: "false"
# --- 显示名称: Issue 发布者/评论者显示姓名, 而不是学号 ---------------
# 导入用户时 full_name = 真实姓名、login = 学号(见 scripts/.../users.py);
# Gitea 默认只显示 login, 打开这个开关后 Issue 的「由 X 创建」、正文/评论作者
# 以及其它用 GetDisplayName() 的地方都改为显示 full_name, 没填姓名的回退学号。
# 证据: models/user/user.go 的 GetDisplayName(); templates/shared/user/authorlink.tmpl。
# 这是站点级设置, 没有按用户的开关。改完需重建容器(up -d)才生效。
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
# --- 数据库 --------------------------------------------------------- # --- 数据库 ---------------------------------------------------------
GITEA__database__DB_TYPE: postgres GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: db:5432 GITEA__database__HOST: db:5432
@@ -108,8 +116,11 @@ services:
GITEA__server__HTTP_ADDR: 0.0.0.0 GITEA__server__HTTP_ADDR: 0.0.0.0
GITEA__server__HTTP_PORT: "3000" GITEA__server__HTTP_PORT: "3000"
GITEA__server__APP_DATA_PATH: /data/gitea GITEA__server__APP_DATA_PATH: /data/gitea
# 现有部署未启用 SSH(git 用户无 .ssh/authorized_keys), 故关闭。 # 关闭 SSH: 界面只提供 HTTP 克隆地址(加公钥时会提示"仅用于提交签名验证")。
# 如需启用容器内置 SSH, 见 deploy/README.md "启用 SSH 克隆"。 # 注意镜像自带 sshd(s6 服务 openssh), 容器内就在 22 上监听 —— 只是没有发布端口。
# 启用要同时改 DISABLE_SSH / SSH_DOMAIN / SSH_PORT 并在 ports 里发布 2222:22,
# 少改一处就会出现 ssh://git@localhost:22/... 这种坏地址: 见
# deploy/README.md「如需启用 SSH 克隆(可选, 默认关闭)」。
GITEA__server__DISABLE_SSH: "true" GITEA__server__DISABLE_SSH: "true"
GITEA__server__LFS_START_SERVER: "true" GITEA__server__LFS_START_SERVER: "true"
GITEA__server__OFFLINE_MODE: ${GITEA_OFFLINE_MODE:-true} GITEA__server__OFFLINE_MODE: ${GITEA_OFFLINE_MODE:-true}
@@ -141,6 +152,9 @@ services:
GITEA__service__ENABLE_NOTIFY_MAIL: "false" GITEA__service__ENABLE_NOTIFY_MAIL: "false"
GITEA__service__ENABLE_CAPTCHA: "false" GITEA__service__ENABLE_CAPTCHA: "false"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false" GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
# 不做通行密钥(WebAuthn): 上游登录页的 passkey 区块只有 tw-hidden 的元素,
# 浏览器不支持条件中介时就渲染成一个空方框; 关闭后区块不再输出。
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "false"
GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE: "false" GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE: "false"
GITEA__service__DEFAULT_ALLOW_CREATE_ORGANIZATION: "true" GITEA__service__DEFAULT_ALLOW_CREATE_ORGANIZATION: "true"
GITEA__service__DEFAULT_ENABLE_TIMETRACKING: "true" GITEA__service__DEFAULT_ENABLE_TIMETRACKING: "true"
@@ -150,7 +164,7 @@ services:
# --- OIDC / OAuth2 -------------------------------------------------- # --- OIDC / OAuth2 --------------------------------------------------
GITEA__openid__ENABLE_OPENID_SIGNIN: "false" GITEA__openid__ENABLE_OPENID_SIGNIN: "false"
GITEA__openid__ENABLE_OPENID_SIGNUP: "true" GITEA__openid__ENABLE_OPENID_SIGNUP: "true"
GITEA__oauth2_client__OPENID_CONNECT_SCOPES: profile GITEA__oauth2_client__OPENID_CONNECT_SCOPES: profile email
GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION: "true" GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION: "true"
GITEA__oauth2_client__USERNAME: userid GITEA__oauth2_client__USERNAME: userid
GITEA__oauth2_client__ACCOUNT_LINKING: auto GITEA__oauth2_client__ACCOUNT_LINKING: auto
@@ -158,6 +172,30 @@ services:
# 这里显式声明, 避免上游改默认值时行为漂移 # 这里显式声明, 避免上游改默认值时行为漂移
GITEA__oauth2__ENABLED: "true" GITEA__oauth2__ENABLED: "true"
# --- 出站代理: 显式给值挡掉 compose 的自动注入, 默认【不用代理】 --------
# ★ docker compose 会把【运行 compose 的那个 shell 里】的 http_proxy/https_proxy
# 自动注入容器。本机登录 shell 里是 127.0.0.1:7890, 而那个地址在容器里指向
# 容器自己, 于是 Gitea 启动时 OIDC discovery 失败:
# initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to
# proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused
# 后果: /user/oauth2/<认证源> 返回 404, 统一身份认证登录不可用(2026-09-11 实际踩到)。
# 显式赋值可以挡住注入 —— 哪怕给的是空值。
#
# 不用代理的理由(2026-09-13 实测):
# * 容器直连外网是通的 —— dl.gitea.com / api.github.com / codeload.github.com
# 在容器里直接 curl 都是 200/301(github.com 主站直连会超时, 但平台不依赖它);
# * 功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连就是 200;
# * 宿主 7890 那个代理是 ssh 转发的开发用代理, 只监听宿主 127.0.0.1,
# 容器里连不上(127.0.0.1:7890 是容器自己; 10.80.42.185:7890 实测 connect refused)。
# 将来真要给容器配代理, 必须是【容器可达】的地址(隧道绑 LAN 口, 或用 host 网络兜底),
# 再在 deploy/.env 里给 GITEA_HTTP_PROXY。
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
http_proxy: ${GITEA_HTTP_PROXY:-}
https_proxy: ${GITEA_HTTPS_PROXY:-}
NO_PROXY: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
no_proxy: ${GITEA_NO_PROXY:-localhost,127.0.0.1,::1,10.80.42.185,.local,.internal}
# --- 管理员限制 ----------------------------------------------------- # --- 管理员限制 -----------------------------------------------------
GITEA__admin__DISABLE_REGULAR_ORG_CREATION: "true" GITEA__admin__DISABLE_REGULAR_ORG_CREATION: "true"
GITEA__admin__EXTERNAL_USER_DISABLE_FEATURES: deletion,manage_credentials,change_username,change_full_name GITEA__admin__EXTERNAL_USER_DISABLE_FEATURES: deletion,manage_credentials,change_username,change_full_name
+10
View File
@@ -0,0 +1,10 @@
# 复制成 .env 后填写(deploy/runner/.env 已 gitignore)
#
# RUNNER_REGISTRATION_TOKEN: 仓库 → Settings → Actions → Runners → 创建 Runner 时给的令牌。
# 一次性, 用完即弃; 注册成功后身份存在 ./data/.runner, 重启不会再注册。
RUNNER_REGISTRATION_TOKEN=
# 默认值在 compose.yaml 里, 需要时再覆盖
#GITEA_INSTANCE_URL=https://cpp.tongji.sh/QA
#RUNNER_NAME=tjhlp-gitea-1
# runner 的 label 不在这里配: 以 config.yaml 的 runner.labels 为准(实测 env 会被忽略)
+33
View File
@@ -0,0 +1,33 @@
# Gitea Actions runner —— 跑在容器里, 由 docker 自己拉起(不需要 root, ymy 在 docker 组即可)。
#
# cd deploy/runner
# cp .env.example .env # 填 RUNNER_REGISTRATION_TOKEN(仓库 → Settings → Actions → Runners)
# docker compose up -d
# docker compose logs -f runner
#
# 详见 ../ci-cd.md §4.2。注册结果存在 ./data/.runner, 重启不会重复注册。
name: gitea-runner
services:
runner:
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1
container_name: gitea-runner
restart: unless-stopped
environment:
# 变量名与镜像里 /usr/local/bin/run.sh 一致
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:-https://cpp.tongji.sh/QA}
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?deploy/runner/.env 里给 RUNNER_REGISTRATION_TOKEN}
GITEA_RUNNER_NAME: ${RUNNER_NAME:-tjhlp-gitea-1}
# 注意: 不要在这里设 GITEA_RUNNER_LABELS —— act_runner 会警告
# "Labels from command will be ignored, use labels defined in config file.",
# label 以 config.yaml 的 runner.labels 为准(实测)。
CONFIG_FILE: /config/config.yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
- ./data:/data # 注册凭据 / 缓存(gitignore)
- ./config.yaml:/config/config.yaml:ro
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
+52
View File
@@ -0,0 +1,52 @@
# act_runner 配置 —— 关键项都有注释, 依据是 act_runner v0.6.1 自带的 generate-config 输出。
log:
level: info
runner:
file: /data/.runner # 与 compose.yaml 的 ./data 挂载对应; 注册后保存在这里
capacity: 1 # 部署必须串行: 一次只跑一个 job
timeout: 30m
labels:
# job 跑在容器里(network: host), 镜像用 Gitea 官方 runner 镜像(实测 arm64 可用)。
# 换成 catthehacker/ubuntu:act-22.04 也可以; 记得同步 compose.yaml 的 GITEA_RUNNER_LABELS。
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
container:
# host: job 容器与宿主共用网络 —— verify.sh 里对 127.0.0.1:2080 的检查才有效,
# 10.80.42.185 也不需要额外放行。
# ⚠️ 这是 runner 级设置, 所以这个 runner 上的【每个】job 都共享宿主网络 —— 还没能
# 收窄的一轴(见 ci-cd.md §7 残留项)。
network: host
# ★ 不把宿主 docker socket 自动挂进 job 容器(默认行为是自动挂 = 每个 job 都能拿到
# root 等价能力)。改成"要用 docker 的 job 自己申报", 并受下面的白名单约束。
docker_host: "-"
# ★ job 允许申报的挂载白名单(gobwas/glob 匹配【挂载源路径】; [] = 一个都不许, ['**'] = 全放)。
# 注意: 全局 options 里的 --volume 也过这道白名单 —— 不在表里的会被
# "[xxx] is not a valid volume, will be ignored" 直接丢弃。2026-09-21 就因为这个
# (当时 options 有挂载但白名单是默认空表)让 job 容器里看不到 /home/ymy/deploy,
# 第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就失败。
#
# 表里的四项分别对应:
# /home/ymy/deploy job 里的工作目录(deploy job 申报, 可写)
# /srv/gitea 部署克隆的 origin 是这里面的本地裸库; 不挂进去
# `git fetch` 会报 "does not appear to be a git repository"
# (2026-09-21 实际踩到), 只读
# /var/run/docker.sock 部署要 `docker compose up -d`, 只给申报它的 job
# /usr/bin/docker 等 docker CLI + compose 插件, 不依赖 job 镜像里带没带
valid_volumes:
- /home/ymy/deploy
- /srv/gitea
- /var/run/docker.sock
- /usr/bin/docker
- /usr/libexec/docker/cli-plugins
# ★ 这里【故意不写】全局 options 挂载: 需要宿主路径/socket 的只有 deploy 这一个 job,
# 由它在 .gitea/workflows/deploy.yml 的 container.volumes 里自己申报(见 ci-cd.md §5.1)。
# 挂在这里等于这个 runner 上的每个 job(比如将来加的 PR 检查/测试)都白拿 socket = root。
# 另外 act_runner 会自动挂 docker.sock, 再在 options 里挂一次会以
# "Duplicate mount point: /var/run/docker.sock" 直接失败(2026-09-13 预演时实测),
# 所以 docker_host: "-" 与 job 自己申报是配套的一对改动。
force_pull: false # 镜像本地已有就不再拉
cache:
enabled: true
dir: /data/cache
+160
View File
@@ -0,0 +1,160 @@
#!/usr/bin/env bash
# main 自动部署 —— 由 .gitea/workflows/deploy.yml 调用, 也可以手工执行。
#
# ./auto-deploy.sh # 部署当前 checkout
# ./auto-deploy.sh <sha> # 部署指定提交
#
# 流程: build.py(生成+校验) → docker compose up -d → custom/ 与上次成功部署的指纹不同
# 就重启 gitea(模板/语言文件是启动时加载的) → 验证(verify.sh + check.sh)
# → 成功则记下 .state/{last-deployed,custom-hash}
# 任一步失败 → 回滚到 deploy/.state/last-deployed 记录的上一个成功提交并强制重启。
# 只动代码与挂载文件; 数据库/`.env`/备份目录全程不参与(见 deploy/ci-cd.md §6)。
set -euo pipefail
REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
STATE_DIR="${REPO_DIR}/deploy/.state"
STATE_FILE="${STATE_DIR}/last-deployed"
HASH_FILE="${STATE_DIR}/custom-hash" # 上次成功部署时 customization/custom/ 的指纹
PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}"
# 本机/内网回环验证不能走代理, 否则会把 200 变成 502(见 deploy/README.md 陷阱 5)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export no_proxy='*' NO_PROXY='*'
# 只补齐标准路径(append): 不要把 /usr/bin 提到最前面 —— 宿主上 /usr/bin/python3 是 3.6
export PATH="${PATH}:/usr/local/bin:/usr/bin:/bin"
# build.py 用了 `from __future__ import annotations`, 需要 python3 >= 3.7。
# 宿主: python3 在 ~/.local/bin(3.14), /usr/bin/python3 是 3.6(Rocky 8);
# job 容器(Ubuntu 22.04): /usr/bin/python3 是 3.10。所以不能盲信 PATH 里的第一个。
# (第一次实测就踩到: 把 /usr/bin 提前 → 用 3.6 跑 build.py → SyntaxError → 语言文件没生成。)
pick_python() {
local c
for c in "$(command -v python3 2>/dev/null)" /usr/local/bin/python3 /usr/bin/python3 "${HOME}/.local/bin/python3"; do
[[ -n ${c} && -x ${c} ]] || continue
if "${c}" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 7) else 1)' 2>/dev/null; then
printf '%s' "${c}"
return 0
fi
done
return 1
}
PY="$(pick_python)" || {
echo "[auto-deploy] 找不到 >= 3.7 的 python3, 中止"
exit 1
}
echo "[auto-deploy] python3: ${PY} ($("${PY}" -V 2>&1))"
mkdir -p "${STATE_DIR}"
TARGET="${1:-$(git -C "${REPO_DIR}" rev-parse HEAD)}"
PREV="$(cat "${STATE_FILE}" 2>/dev/null || true)"
# job 容器里是 root, 会把 clone 里新生成的文件留成 root 所有, 影响宿主上的手工 git 操作。
# 结束时(无论成功失败)把所有权还回去。
restore_owner() {
[[ "$(id -u)" == 0 ]] || return 0
chown -R "${DEPLOY_OWNER_UID:-1001}:${DEPLOY_OWNER_GID:-1001}" "${REPO_DIR}" 2>/dev/null || true
}
trap restore_owner EXIT
# workflow 的 concurrency 之外再加一道, 防止手工执行与 CI 撞车
exec 9>"${STATE_DIR}/lock"
flock -n 9 || {
echo "[auto-deploy] 已有部署在跑, 本次退出"
exit 0
}
echo "[auto-deploy] 目标 ${TARGET} (上次成功部署: ${PREV:-无})"
cd "${REPO_DIR}"
# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面。
# 这些是 Gitea 启动时加载的, 变了必须重启容器才生效(README §3), 而 `compose up -d`
# 只在 compose 配置变化时才重建容器 —— 所以自己比指纹, 变了就 restart。
# ⚠️ 比的是【与上次成功部署的指纹】(.state/custom-hash), 不是 build.py 前后:
# 后者只能发现语言文件被重新生成, 纯模板改动前后完全一样 → 永远不重启 → 容器继续
# 用启动时加载的旧模板 → check.sh 断言失败 → 整个部署回滚。2026-09-22 实际踩到
# (「提问指南」换地址那个提交就这么被回滚了)。
custom_hash() {
(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
}
# compose 的 bind mount 源目录必须先存在【且属于当前用户】: 源目录不存在时 docker 会
# 以 root 创建它, 之后 build.py 就写不进去(全新克隆第一次部署时真实踩到, 于是语言文件
# 生成失败、「工单」回来了)。仓库里 custom/options/.gitkeep 从结构上避免这一点,
# 这里再兜底检查一次, 失败就说清楚怎么办。
prepare_custom_dirs() {
local d
for d in options public templates; do
if [[ ! -d customization/custom/${d} ]]; then
mkdir -p "customization/custom/${d}" 2>/dev/null || {
echo "[auto-deploy] 无法创建 customization/custom/${d}" >&2
return 1
}
fi
if [[ ! -w customization/custom/${d} ]]; then
echo "[auto-deploy] customization/custom/${d} 不可写 —— 很可能是 docker 以 root 创建过它。" >&2
echo " 删除后重试(宿主上需 sudo; job 容器里是 root): rm -rf customization/custom/${d}" >&2
return 1
fi
done
}
deploy() {
local force="${1:-}" now last
prepare_custom_dirs || return 1
"${PY}" customization/build.py || return 1 # 生成语言文件 + 规范 custom/ 权限
"${PY}" customization/build.py --check || return 1 # 生成物/权限校验, 不过就中止, 不碰容器
now="$(custom_hash)"
(cd deploy && docker compose up -d) || return 1 # 幂等: 只有配置/挂载/镜像变化时才重建
last="$(cat "${HASH_FILE}" 2>/dev/null || true)"
if [[ -n ${force} || ${now} != "${last}" ]]; then
if [[ -n ${force} ]]; then
echo "[auto-deploy] 回滚路径: 重启 gitea, 让回退后的模板/语言文件生效"
else
echo "[auto-deploy] custom/ 与上次成功部署不同, 重启 gitea 使模板/语言文件生效"
fi
# 用 restart 而不是 up -d: compose 配置没变时 up -d 不重建容器, 而模板/语言文件
# 是启动时加载的。restart 还会【重新解析 bind mount】—— 挂载源目录被「删掉再建」
# (例如某个提交把 public/ 下的文件删光了, git 会顺手删掉空目录)之后, 容器里
# 仍然挂着旧 inode(一个空目录), 只有重新 start 才会挂到新目录上。
# 2026-09-22 实际踩到: 线上 /QA/assets/tjhlp/ask-guide.html 变成 404。
(cd deploy && docker compose restart gitea) || return 1
else
echo "[auto-deploy] custom/ 与上次成功部署一致, 不重启"
fi
}
verify() {
(cd deploy && ./scripts/verify.sh) || return 1 # 容器健康 + 本机 API + 经 Apache 反代
if [[ -x ${REPO_DIR}/customization/check.sh ]]; then
"${REPO_DIR}/customization/check.sh" "${PUBLIC_URL}" || return 1 # 定制断言
else
# 回滚到旧版本时那个版本可能还没有这个脚本 —— 那不是失败
echo "[auto-deploy] (${TARGET} 这个版本没有 customization/check.sh, 跳过定制断言)"
fi
}
rollback() {
if [[ -z ${PREV} ]]; then
echo "[auto-deploy] 没有历史成功版本可回退, 保持现状"
return 0
fi
echo "[auto-deploy] 回滚到 ${PREV}"
# -f: 旧版本里可能没有 deploy/runner/* 这类文件, 它们在新版本是"未跟踪文件",
# 会挡住普通 checkout(实测), 这里直接覆盖
git checkout -f --detach "${PREV}"
deploy force || true # force: 失败的那次可能已经用新模板重启过容器, 必须再重启回去
verify || true
}
# 包成一个函数再放进 if: 避免依赖 "&& 列表最后一个命令在 if 条件里是否触发 errexit" 这类细节
pipeline() { deploy && verify; }
if pipeline; then
echo "${TARGET}" >"${STATE_FILE}"
custom_hash >"${HASH_FILE}" # 记下本次成功部署的 custom/ 指纹, 供下次比较
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
else
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
rollback
exit 1
fi
+2 -1
View File
@@ -30,7 +30,8 @@ issue-templates/
## config.yaml 里的链接与占位符 ## config.yaml 里的链接与占位符
`config.yaml` 的 `contact_links` 是「新建 Issue」页面上的引导入口, 目前指向**课程官网** `config.yaml` 的 `contact_links` 是「新建 Issue」页面上的引导入口, 目前指向**课程官网**
(学会提问 / 课程信息 / 常见问题), 把答疑平台和官网串起来。课程官网地址是硬编码常量 (提问指南 / 课程信息), 把答疑平台和官网串起来。提问指南只在官网保留一份
(`https://cpp.tongji.sh/Website/qa/ask/`, 平台内不再有副本); 课程官网地址是硬编码常量
(`https://cpp.tongji.sh/Website/`), 换域名时两个 `config.yaml` 要一起改。 (`https://cpp.tongji.sh/Website/`), 换域名时两个 `config.yaml` 要一起改。
平台自身的链接用占位符, 避免把学期组织名写死: 平台自身的链接用占位符, 避免把学期组织名写死:
@@ -1,11 +1,8 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: 提问前必读 · 学会提问 - name: 提问前必读 · 提问指南
url: https://cpp.tongji.sh/Website/ask-question/ url: https://cpp.tongji.sh/Website/qa/ask/
about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答 about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 课程官网 - name: 课程官网
url: https://cpp.tongji.sh/Website/ url: https://cpp.tongji.sh/Website/
about: 课程信息、作业说明、环境配置要求、常见问题 about: 课程信息、作业说明、环境配置要求、常见问题
- name: 答疑平台提问指南
url: "{{BASE_URL}}/assets/tjhlp/ask-guide.html"
about: 搜索 Issue、选择模板、填写信息、关闭 Issue 的平台内速查
@@ -3,9 +3,9 @@ contact_links:
- name: 一般性问题请到 general 仓库提问 - name: 一般性问题请到 general 仓库提问
url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose" url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose"
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库 about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
- name: 提问前必读 · 学会提问 - name: 提问前必读 · 提问指南
url: https://cpp.tongji.sh/Website/ask-question/ url: https://cpp.tongji.sh/Website/qa/ask/
about: 课程官网上的提问规范。不合规范的提问很可能不会得到回答 about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 课程官网 - name: 课程官网
url: https://cpp.tongji.sh/Website/ url: https://cpp.tongji.sh/Website/
about: 课程信息、作业说明、环境配置要求、常见问题 about: 课程信息、作业说明、环境配置要求、常见问题
+14
View File
@@ -156,6 +156,20 @@ uv run tjhlp labels sync tjhlp-2025f/hw03
uv run tjhlp webhooks list tjhlp-2025f/general uv run tjhlp webhooks list tjhlp-2025f/general
``` ```
### 显示名维护(学号-姓名)
Issue 页显示的是 `full_name`。OIDC 登录时会把 `full_name` 覆盖成认证源
`FullNameClaimName` 对应的 claim(`display_name` = `学号-姓名`),因此**存量用户
需要重新登录**才会刷新。若不想等用户重登,用 `tools/fix_full_name.py` 直接刷一遍:
```bash
export TJHLP_GITEA_TOKEN=<token> # 或建 scripts/.secrets.toml
uv run python tools/fix_full_name.py # dry-run,只打印
uv run python tools/fix_full_name.py --apply # 实际写入
```
脚本只改 `full_name`(成 `学号-姓名`),不动用户名/邮箱和团队归属;默认跳过 `admin`。
### 学期结束清理 ### 学期结束清理
```bash ```bash
+1 -1
View File
@@ -1,5 +1,5 @@
[default.gitea] [default.gitea]
url = "http://10.80.42.185:3000" url = "http://127.0.0.1:2080"
# 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。 # 同学实际访问的平台地址(Apache 反代 /QA -> 127.0.0.1:2080)。
# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。 # 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。
public_url = "https://cpp.tongji.sh/QA" public_url = "https://cpp.tongji.sh/QA"