21 Commits
Author SHA256 Message Date
admin 9446850182 feat: Issue 发布者/回答者显示姓名, 而不是学号
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 前后
事故经过(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/), 删掉平台内副本
官网改版后提问指南在 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 自己申报挂载
原来 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
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
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
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
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/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
admin 68fb567cb3 feat: Issue 模板引导链接改指课程官网, 平台地址改由 public_url 注入
- 两个 config.yaml 的 contact_links 从 example.com 换成真实入口:
  官网《学会提问》/ 课程官网 / 平台提问速查, 让答疑平台与官网互相导流
- 模板支持 {{BASE_URL}}/{{ORG}}/{{REPO}} 占位符, 推送时替换,
  换学期建新组织不用改模板; 未配置时保留占位符并告警而不是推坏链接
- scripts: 新增 gitea.public_url(对外地址, 与 CLI 用的 url 区分),
  utils.web_base_url()/render_template_placeholders() 及单元测试
2026-09-11 17:07:11 +08:00
admin 44b174d319 feat: 部署接入定制覆盖层, 并补去 Gitea 化的元信息与页脚配置
- compose.yaml: 三个只读挂载到 /data/gitea/{templates,public,options};
  官方镜像 GITEA_CUSTOM=/data/gitea, 挂 /data/gitea/custom 是无效的
- compose.yaml: [ui.meta] 作者/描述/关键词与 SHOW_FOOTER_POWERED_BY/VERSION,
  环境变量里段名的点要编码成 _0X2E_(GITEA__ui_0X2E_meta__DESCRIPTION)
- .env.example: 新增 GITEA_CUSTOM_DIR(指向 customization/custom)
- README: 新增已知陷阱 3(定制文件权限导致 [F] 拒绝启动, 含体检/修复命令),
  并在升级流程里加入定制基线的同步与校验步骤
2026-09-11 17:07:11 +08:00
admin 7d19e2729c feat: 新增 Gitea 定制机制(首页/中文语言/去 Gitea 化)与本地预览
不改 Go 代码、不 fork, 只用官方 CustomPath 覆盖层 + app.ini/env 配置:

- custom/templates: 整文件覆盖 home.tmpl(落地页换成答疑平台介绍)与
  base/head_navbar.tmpl(docs.gitea.com -> 站内提问指南、新增课程官网入口)
- custom/public/assets/tjhlp/ask-guide.html: 站内提问指南静态页
- overrides/ + build.py: 由上游快照确定性生成整份 locale_zh-CN.json
  (工单 -> Issue 等 133 处), 带占位符校验; 缺失键会退回英文, 必须整份覆盖
- build.py 同时负责规范 custom/ 权限: 容器内 Gitea 以 git(982) 运行,
  文件若为 600 只读挂载也会 permission denied 并拒绝启动(生产踩过)
- upstream/<版本>/ + fetch-upstream.sh: 上游基线, 供升级时 diff 与重生成
- preview/: 独立 compose + preview.sh(up/check/reload/admin/reset),
  与生产隔离(独立端口 2081/数据目录/sqlite), 用同一镜像版本验证效果
- website-linkage.md: 官网(VitePress)侧的联动改动提案
2026-09-11 17:07:05 +08:00
admin 79256c5be0 feat: 新增 Docker Compose 部署方案, 移除未验证的 ansible 草案
原 ansible/ 方案从未在任何环境验证过, 且与本机实际状态严重不符(硬编码
amd64 二进制、会覆盖生产 /etc/gitea/app.ini、会启动 firewalld 切断其它
服务、建的库名与现网不一致); 加上宿主机 Rocky 8 的系统 Python 无法升级,
新版 ansible 也跑不起来。改为 Docker Compose。

新增 deploy/:
- compose.yaml    版本锁定; Gitea 只发布 127.0.0.1:2080(Apache 反代无需
                  改动), PostgreSQL 不发布端口; 配置全部由
                  GITEA__section__KEY 环境变量注入; 数据用 bind mount
- db/Dockerfile   官方 postgres 只生成 en_US.UTF-8, 这里补 zh_CN.UTF-8,
                  与现有集群 collation 保持一致
- scripts/        backup.sh(pg_dump + 数据 tar + SHA256SUMS)、
                  restore.sh(默认 dry-run, 校验后还原, 拒收宿主布局备份)、
                  verify.sh(容器健康 + 回环 API + 经 Apache 反代)

文档 deploy/README.md 以 部署/备份/恢复/升级 四条流程为主线, 并记录本机
踩过的四个陷阱: PG18 挂载点、s6 chown 守卫、APP_NAME 只能走裸变量、
HTTP 代理导致的假 502。

一次性迁移脚本(install-docker / configure-docker-proxy / preflight /
migrate-from-binary)已清理, 相应步骤内联进文档。

实测: 源 116 表 → 目标 116 表, /api/healthz 200, 经 Apache /QA 200,
站点名与 OIDC 登录源注册正常。
2026-09-11 16:00:15 +08:00
74 changed files with 8921 additions and 1408 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
+11 -9
View File
@@ -14,8 +14,17 @@ credentials_*.csv
*.pem *.pem
*.key *.key
# Ansible # Deployment (docker compose)
*.retry deploy/.env
deploy/backups/
# CI/CD: 部署状态(上次成功的 SHA)与 runner 的注册凭据/缓存
deploy/.state/
deploy/runner/.env
deploy/runner/data/
# Customization
customization/custom/options/locale/locale_zh-CN.json
customization/preview/data/
# IDE # IDE
.idea/ .idea/
@@ -33,10 +42,3 @@ Thumbs.db
# OpenCode # OpenCode
.opencode/ .opencode/
# Server inventory
ansible/inventory/hosts.yml
ansible/inventory/group_vars/all.yml
# Docker Compose local config
deploy/compose/.env
+40 -39
View File
@@ -17,43 +17,30 @@
```text ```text
tjhlp-gitea/ tjhlp-gitea/
├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL) ├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
├── deploy/ 测试使用的部署方案(如 Docker Compose) ├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览
├── issue-templates/ Issue 模板(按仓库类型区分) ├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具 └── scripts/ Python CLI 管理工具
``` ```
## 快速开始 ## 快速开始
### 1. 选择部署方式 ### 1. 部署服务器
本项目当前提供两种并行的单机部署方式: 需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。
- **Ansible**: 现有正式方案, 面向 Rocky Linux 8.10 主机, 直接安装 Gitea 二进制 + PostgreSQL + systemd
- **Docker Compose**: 测试方案, 面向单机容器部署, 默认只包含 Gitea + PostgreSQL, 提供管理员初始化脚本, 反向代理/TLS 由外部处理
如果你使用 Docker Compose, 先参考 [deploy/compose/README.md](deploy/compose/README.md) 完成服务启动, 然后再回到下面的“初始化平台”步骤。
### 2. 使用 Ansible 部署服务器
需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。
```bash ```bash
cd ansible cd deploy
cp inventory/hosts.yml.example inventory/hosts.yml cp .env.example .env # 填写地址、密钥、密码
cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml docker compose config --quiet # 校验 compose 与 .env 插值
docker compose up -d --build
sudo ./scripts/verify.sh # 体检
``` ```
编辑 ansible/inventory/hosts.yml 填入服务器地址 完整的部署步骤(Docker 安装、外网代理、RPM 冲突处理), 以及 **备份 / 恢复 / 升级**
编辑 ansible/inventory/group_vars/all.yml 修改域名、密码等 流程, 见 [`deploy/README.md`](deploy/README.md)。
```bash ### 2. 初始化平台
ansible-playbook playbook.yml
```
部署完成后, Ansible 会自动创建管理员账号并输出访问地址。
### 3. 初始化平台
登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: 登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后:
@@ -68,7 +55,7 @@ uv run tjhlp setup init --org tjhlp-2025f
这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。
### 4. 导入用户 ### 3. 导入用户
准备 CSV 文件(格式见 `scripts/example/members.csv`): 准备 CSV 文件(格式见 `scripts/example/members.csv`):
@@ -83,7 +70,7 @@ uv run tjhlp users create --file members.csv --org tjhlp-2025f
uv run tjhlp notify send-credentials --file credentials_*.csv uv run tjhlp notify send-credentials --file credentials_*.csv
``` ```
### 5. 创建作业仓库 ### 4. 创建作业仓库
```bash ```bash
uv run tjhlp repos create-homework --org tjhlp-2025f --number 1 uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
@@ -103,8 +90,8 @@ uv run tjhlp repos create-homework --org tjhlp-2025f --number 1
```bash ```bash
cd scripts cd scripts
uv sync --extra dev uv sync --extra dev
uv run pytest tests/ -v --basetemp .pytest_tmp # 运行全部测试 uv run pytest tests/ -v # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp # 带覆盖率 uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率
``` ```
当前测试套件包含 99 个测试用例, 覆盖: 当前测试套件包含 99 个测试用例, 覆盖:
@@ -115,13 +102,13 @@ uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tm
- **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None - **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None
- **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程 - **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程
### Ansible 静态检查 ### 部署配置检查
```bash ```bash
cd ansible cd deploy
ansible-playbook --syntax-check playbook.yml # 语法检查 docker compose config --quiet # 校验 compose 与 .env 插值
yamllint -c .yamllint.yml . # YAML 格式 sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代)
ansible-lint playbook.yml # 最佳实践 ./scripts/restore.sh --list # 查看可用备份及校验状态
``` ```
### Issue Templates 验证 ### Issue Templates 验证
@@ -130,17 +117,31 @@ ansible-lint playbook.yml # 最佳实践
yamllint issue-templates/ # YAML 语法 yamllint issue-templates/ # YAML 语法
``` ```
### 定制(Gitea 客制化)
```bash
python3 customization/build.py # 生成定制语言文件
python3 customization/build.py --check # 校验生成物是否最新
customization/preview/preview.sh up # 起本地预览(127.0.0.1:2081)
customization/preview/preview.sh semester # 造一个学期组织, 看首页答疑入口卡片
customization/preview/preview.sh check # 自动校验首页/登录页/卡片/页脚/meta/术语
```
机制调查、日常改法与部署/升级流程见 [`customization/README.md`](customization/README.md);
与课程官网(<https://cpp.tongji.sh/Website/>)的互相导流见
[`customization/website-linkage.md`](customization/website-linkage.md)。
详见各子目录的 README。 详见各子目录的 README。
## 技术栈 ## 技术栈
| 组件 | 技术选型 | | 组件 | 技术选型 |
| ------ | ---------- | | ------ | ---------- |
| Git 平台 | Gitea(二进制 + systemd) | | Git 平台 | Gitea(Docker 容器) |
| 数据库 | PostgreSQL 18 | | 数据库 | PostgreSQL 18(Docker 容器) |
| 服务器 | Rocky Linux 8.10 | | 服务器 | Rocky Linux 8.10 (aarch64) |
| 部署工具 | Ansible / Docker Compose | | 部署工具 | Docker Compose(见 `deploy/`) |
| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | | 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf |
| 包管理 | uv | | 包管理 | uv |
| 测试框架 | pytest + respx + pytest-cov | | 测试框架 | pytest + respx + pytest-cov |
| 代码检查 | ruff, yamllint, ansible-lint | | 代码检查 | ruff, yamllint |
-13
View File
@@ -1,13 +0,0 @@
---
extends: default
rules:
line-length:
max: 160
truthy:
allowed-values: ["true", "false", "yes", "no"]
comments:
min-spaces-from-content: 1
indentation:
spaces: 2
indent-sequences: consistent
-206
View File
@@ -1,206 +0,0 @@
# Ansible 部署
使用 Ansible 在 Rocky Linux 8.10 服务器上自动部署 Gitea + PostgreSQL 18。
## 前置要求
- 控制机安装 Ansible >= 2.12
- 目标服务器运行 Rocky Linux 8.10(或兼容的 RHEL 8 系发行版)
- 控制机可通过 SSH 连接目标服务器(建议配置密钥认证)
- 安装 Ansible 依赖(collection):
```bash
ansible-galaxy collection install -r requirements.yml
```
## 目录结构
```
ansible/
├── ansible.cfg Ansible 配置
├── playbook.yml 主 Playbook
├── requirements.yml Ansible collection 依赖
├── .yamllint.yml YAML lint 配置
├── inventory/
│ ├── hosts.yml 主机清单
│ └── group_vars/
│ └── all.yml 全局变量
└── roles/
├── common/ 基础系统配置
│ └── tasks/main.yml
├── postgresql/ PostgreSQL 18 安装与配置
│ ├── tasks/main.yml
│ ├── handlers/main.yml
│ └── templates/
│ └── pg_hba.conf.j2
└── gitea/ Gitea 安装与配置
├── tasks/
│ ├── main.yml
│ ├── install.yml 下载二进制(在线获取最新版本)
│ └── configure.yml 生成配置、创建管理员
├── handlers/main.yml
└── templates/
├── app.ini.j2 Gitea 配置文件模板
└── gitea.service.j2 systemd 服务文件
```
## 配置
### 1. 主机清单
编辑 `inventory/hosts.yml`:
```yaml
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际 IP
ansible_user: root
```
### 2. 变量配置
编辑 `inventory/group_vars/all.yml`, **必须修改**的项:
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `gitea_domain` | Gitea 访问域名或 IP | `gitea.example.com` |
| `gitea_admin_password` | 管理员初始密码 | `ChangeMe!2025` |
| `gitea_db_password` | 数据库密码 | `change_this_db_password` |
可选变量:
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `gitea_version` | 指定 Gitea 版本, 留空自动获取最新 | `""` |
| `gitea_http_port` | HTTP 端口 | `3000` |
| `gitea_admin_user` | 管理员用户名 | `admin` |
| `gitea_admin_email` | 管理员邮箱 | `admin@tongji.edu.cn` |
| `postgresql_version` | PostgreSQL 版本号 | `18` |
| `gitea_secret_key` | 安全密钥, 留空自动生成 | `""` |
| `gitea_internal_token` | 内部令牌, 留空自动生成 | `""` |
**安全建议**: 生产部署时, `gitea_admin_password` 和 `gitea_db_password` 应使用 `ansible-vault` 加密, 而非明文写在 `all.yml` 中。
## 使用方法
### 完整部署
```bash
ansible-playbook playbook.yml
```
### 按 Role 单独运行
```bash
# 仅运行基础配置
ansible-playbook playbook.yml --tags common
# 仅运行 PostgreSQL
ansible-playbook playbook.yml --tags postgresql
# 仅运行 Gitea(安装 + 配置)
ansible-playbook playbook.yml --tags gitea
```
### 更新系统软件包(默认不执行)
```bash
ansible-playbook playbook.yml --tags update-system
```
## Role 说明
### common
- 安装基础软件包(git, wget, curl 等)
- 创建 `git` 系统用户
- 配置 firewalld 开放 Gitea 端口
- 创建 Gitea 所需的目录结构并设置权限
### postgresql
- 添加 PostgreSQL 官方 Yum 仓库
- 禁用系统自带的 postgresql 模块
- 安装 PostgreSQL(版本由 `postgresql_version` 变量控制, 默认 18)并初始化数据库集群
- 配置 `pg_hba.conf` 认证方式为 md5
- 创建 Gitea 所需的数据库和用户
### gitea
- **安装**: 在线获取最新版本号(通过 `dl.gitea.com/gitea/version.json`), 下载对应的 linux-amd64 二进制到 `/usr/local/bin/gitea`。支持通过 `gitea_version` 变量锁定版本
- **配置**: 通过 `gitea generate secret` 自动生成安全密钥, 渲染 `app.ini` 配置模板(禁用注册、禁用邮件、启用 Webhook), 部署 systemd 服务
- **初始化**: 等待 Gitea 启动后, 通过 `gitea admin user create` 创建管理员账号
### app.ini 关键配置
| 配置项 | 值 | 说明 |
|--------|-----|------|
| `INSTALL_LOCK` | `true` | 跳过 Web 安装向导 |
| `DISABLE_REGISTRATION` | `true` | 禁止自助注册 |
| `ENABLE_NOTIFY_MAIL` | `false` | 不使用邮件通知 |
| `ALLOWED_HOST_LIST` | `*` | 允许 Webhook 访问任意主机 |
| `DEFAULT_REPO_UNITS` | `repo.code,repo.issues` | 新仓库默认只开启代码和 Issue |
## 部署完成后
Playbook 执行完毕后会输出:
```
==========================================
Gitea 答疑平台部署完成!
==========================================
访问地址: http://gitea.example.com:3000
管理员: admin
==========================================
后续步骤:
1. 登录管理员账号并修改初始密码
2. 创建 API Token (设置 -> 应用 -> 生成令牌)
3. 配置 Python CLI 工具并执行 tjhlp setup init
==========================================
```
## 测试与验证
### 静态检查
无需连接服务器即可执行:
```bash
# Playbook 语法检查
ansible-playbook --syntax-check playbook.yml
# YAML 格式检查(需要 pip install yamllint)
yamllint -c .yamllint.yml .
# Ansible 最佳实践检查(需要 pip install ansible-lint)
ansible-lint playbook.yml
```
### Dry Run
模拟执行, 不做实际变更(需要能 SSH 到目标服务器):
```bash
ansible-playbook playbook.yml --check
```
### 集成测试(可选)
如果需要在本地完整测试部署流程, 推荐使用 [Molecule](https://ansible.readthedocs.io/projects/molecule/) + Vagrant:
```bash
pip install molecule molecule-vagrant pytest-testinfra
cd roles/gitea && molecule test
```
由于 Rocky 8 + systemd 在 Docker 中支持不完整, Vagrant(VirtualBox)是更可靠的测试环境。
### 部署后验证清单
部署完成后应检查:
- [ ] Gitea Web 界面可访问(`http://{domain}:{port}`)
- [ ] 管理员账号可登录
- [ ] PostgreSQL 服务运行中(`systemctl status postgresql-{version}`)
- [ ] Gitea 服务运行中(`systemctl status gitea`)
- [ ] 防火墙已开放对应端口(`firewall-cmd --list-ports`)
-10
View File
@@ -1,10 +0,0 @@
[defaults]
inventory = inventory/hosts.yml
roles_path = roles
host_key_checking = False
retry_files_enabled = False
[privilege_escalation]
become = True
become_method = sudo
become_user = root
-42
View File
@@ -1,42 +0,0 @@
---
# =============================================================================
# Gitea 答疑平台部署变量
# =============================================================================
# -----------------------------------------------------------------------------
# Gitea 基础配置
# -----------------------------------------------------------------------------
# 留空则自动获取最新版本, 填写则使用指定版本(如 "1.25.1")
gitea_version: ""
gitea_http_port: 3000
gitea_domain: "gitea.example.com" # 替换为实际域名或 IP
gitea_app_name: "同济大学高级语言程序设计答疑平台"
# -----------------------------------------------------------------------------
# Gitea 管理员账号(首次部署自动创建, 部署后请修改密码)
# -----------------------------------------------------------------------------
gitea_admin_user: "admin"
gitea_admin_password: "ChangeMe!2026" # 部署后务必修改
gitea_admin_email: "[email protected]"
# -----------------------------------------------------------------------------
# PostgreSQL 数据库配置
# -----------------------------------------------------------------------------
postgresql_version: 18
gitea_db_name: "gitea"
gitea_db_user: "gitea"
gitea_db_password: "change_this_db_password" # 请修改为强密码
# -----------------------------------------------------------------------------
# Webhook 配置
# -----------------------------------------------------------------------------
gitea_webhook_allowed_hosts: "*"
gitea_webhook_skip_tls: "false"
# -----------------------------------------------------------------------------
# 安全密钥(留空则自动生成, 生成后建议记录保存)
# -----------------------------------------------------------------------------
gitea_secret_key: ""
gitea_internal_token: ""
gitea_lfs_jwt_secret: ""
@@ -1,42 +0,0 @@
---
# =============================================================================
# Gitea 答疑平台部署变量
# =============================================================================
# -----------------------------------------------------------------------------
# Gitea 基础配置
# -----------------------------------------------------------------------------
# 留空则自动获取最新版本, 填写则使用指定版本(如 "1.25.1")
gitea_version: ""
gitea_http_port: 3000
gitea_domain: "gitea.example.com" # 替换为实际域名或 IP
gitea_app_name: "同济大学高级语言程序设计答疑平台"
# -----------------------------------------------------------------------------
# Gitea 管理员账号(首次部署自动创建, 部署后请修改密码)
# -----------------------------------------------------------------------------
gitea_admin_user: "admin"
gitea_admin_password: "ChangeMe!2026" # 部署后务必修改
gitea_admin_email: "[email protected]"
# -----------------------------------------------------------------------------
# PostgreSQL 数据库配置
# -----------------------------------------------------------------------------
postgresql_version: 18
gitea_db_name: "gitea"
gitea_db_user: "gitea"
gitea_db_password: "change_this_db_password" # 请修改为强密码
# -----------------------------------------------------------------------------
# Webhook 配置
# -----------------------------------------------------------------------------
gitea_webhook_allowed_hosts: "*"
gitea_webhook_skip_tls: "false"
# -----------------------------------------------------------------------------
# 安全密钥(留空则自动生成, 生成后建议记录保存)
# -----------------------------------------------------------------------------
gitea_secret_key: ""
gitea_internal_token: ""
gitea_lfs_jwt_secret: ""
-7
View File
@@ -1,7 +0,0 @@
---
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际服务器 IP
ansible_user: root # 替换为实际 SSH 用户
# ansible_ssh_private_key_file: ~/.ssh/id_rsa
-7
View File
@@ -1,7 +0,0 @@
---
all:
hosts:
gitea-server:
ansible_host: 192.168.1.100 # 替换为实际服务器 IP
ansible_user: root # 替换为实际 SSH 用户
# ansible_ssh_private_key_file: ~/.ssh/id_rsa
-54
View File
@@ -1,54 +0,0 @@
---
# =============================================================================
# Gitea 答疑平台部署 Playbook
#
# 使用方法:
# ansible-playbook playbook.yml
#
# 仅运行某个 role:
# ansible-playbook playbook.yml --tags postgresql
# ansible-playbook playbook.yml --tags gitea
# =============================================================================
- name: 部署 Gitea 答疑平台
hosts: all
become: true
pre_tasks:
- name: 检查操作系统
assert:
that:
- ansible_os_family == "RedHat"
- ansible_distribution_major_version | int >= 8
fail_msg: "此 Playbook 仅支持 RHEL/Rocky Linux 8+"
- name: 更新系统软件包
dnf:
name: "*"
state: latest
tags: [never, update-system]
roles:
- role: common
tags: [common]
- role: postgresql
tags: [postgresql, database]
- role: gitea
tags: [gitea]
post_tasks:
- name: 部署完成信息
debug:
msg: |
==========================================
Gitea 答疑平台部署完成!
==========================================
访问地址: http://{{ gitea_domain }}:{{ gitea_http_port }}
管理员: {{ gitea_admin_user }}
Gitea 版本: {{ gitea_resolved_version }}
==========================================
后续步骤:
1. 登录管理员账号并修改初始密码
2. 创建 API Token (设置 -> 应用 -> 生成令牌)
3. 配置 Python CLI 工具并执行 tjhlp setup init
==========================================
-4
View File
@@ -1,4 +0,0 @@
---
collections:
- name: community.postgresql
version: ">=3.0.0"
-61
View File
@@ -1,61 +0,0 @@
---
# roles/common/tasks/main.yml
# 基础系统配置: 安装依赖包、创建 git 用户、配置防火墙、创建目录结构
- name: 安装基础依赖包
dnf:
name:
- git
- wget
- curl
state: present
- name: 创建 git 用户组
group:
name: git
system: yes
state: present
- name: 创建 git 系统用户
user:
name: git
group: git
system: yes
shell: /bin/bash
home: /home/git
create_home: yes
comment: "Git Version Control"
- name: 创建 Gitea 数据目录
file:
path: "{{ item.path }}"
state: directory
owner: "{{ item.owner }}"
group: "{{ item.group }}"
mode: "{{ item.mode }}"
loop:
- { path: /var/lib/gitea, owner: git, group: git, mode: "0750" }
- { path: /var/lib/gitea/custom, owner: git, group: git, mode: "0750" }
- { path: /var/lib/gitea/data, owner: git, group: git, mode: "0750" }
- { path: /var/lib/gitea/log, owner: git, group: git, mode: "0750" }
- name: 创建 Gitea 配置目录
file:
path: /etc/gitea
state: directory
owner: root
group: git
mode: "0770"
- name: 确保 firewalld 正在运行
systemd:
name: firewalld
state: started
enabled: yes
- name: 开放 Gitea HTTP 端口
firewalld:
port: "{{ gitea_http_port }}/tcp"
permanent: yes
immediate: yes
state: enabled
-9
View File
@@ -1,9 +0,0 @@
---
- name: 重载 systemd
systemd:
daemon_reload: yes
- name: 重启 Gitea
systemd:
name: gitea
state: restarted
-100
View File
@@ -1,100 +0,0 @@
---
# roles/gitea/tasks/configure.yml
# 配置 Gitea: 生成密钥、app.ini、systemd 服务、创建管理员
- name: 生成 SECRET_KEY
command: /usr/local/bin/gitea generate secret SECRET_KEY
register: gitea_secret_key_result
changed_when: false
when: gitea_secret_key is not defined or gitea_secret_key == ""
- name: 保存 SECRET_KEY
set_fact:
gitea_secret_key: "{{ gitea_secret_key_result.stdout }}"
when: gitea_secret_key is not defined or gitea_secret_key == ""
- name: 生成 INTERNAL_TOKEN
command: /usr/local/bin/gitea generate secret INTERNAL_TOKEN
register: gitea_internal_token_result
changed_when: false
when: gitea_internal_token is not defined or gitea_internal_token == ""
- name: 保存 INTERNAL_TOKEN
set_fact:
gitea_internal_token: "{{ gitea_internal_token_result.stdout }}"
when: gitea_internal_token is not defined or gitea_internal_token == ""
- name: 生成 LFS_JWT_SECRET
command: /usr/local/bin/gitea generate secret LFS_JWT_SECRET
register: gitea_lfs_jwt_result
changed_when: false
when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == ""
- name: 保存 LFS_JWT_SECRET
set_fact:
gitea_lfs_jwt_secret: "{{ gitea_lfs_jwt_result.stdout }}"
when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == ""
- name: 部署 Gitea 配置文件
template:
src: app.ini.j2
dest: /etc/gitea/app.ini
owner: root
group: git
mode: "0640"
notify: 重启 Gitea
- name: 部署 systemd 服务文件
template:
src: gitea.service.j2
dest: /etc/systemd/system/gitea.service
owner: root
group: root
mode: "0644"
notify:
- 重载 systemd
- 重启 Gitea
- name: 启用并启动 Gitea 服务
systemd:
name: gitea
state: started
enabled: yes
- name: 等待 Gitea 就绪
uri:
url: "http://127.0.0.1:{{ gitea_http_port }}/api/v1/version"
method: GET
status_code: 200
register: gitea_health
until: gitea_health.status == 200
retries: 30
delay: 2
- name: 显示 Gitea 版本
debug:
msg: "Gitea {{ gitea_health.json.version }} 已启动"
- name: 创建管理员账号
command: >
/usr/local/bin/gitea admin user create
--username {{ gitea_admin_user }}
--password {{ gitea_admin_password }}
--email {{ gitea_admin_email }}
--admin
--config /etc/gitea/app.ini
become: true
become_user: git
environment:
GITEA_WORK_DIR: /var/lib/gitea
register: admin_create
changed_when: "'has been successfully created' in admin_create.stdout"
failed_when: >
admin_create.rc != 0 and
'already exists' not in admin_create.stderr
no_log: true
- name: 收紧配置目录权限
file:
path: /etc/gitea
mode: "0750"
-50
View File
@@ -1,50 +0,0 @@
---
# roles/gitea/tasks/install.yml
# 下载并安装 Gitea 二进制文件
- name: 获取 Gitea 最新版本信息
uri:
url: https://dl.gitea.com/gitea/version.json
return_content: yes
register: gitea_version_json
until: gitea_version_json.status == 200
retries: 3
delay: 2
when: gitea_version == ""
- name: 解析最新版本号
set_fact:
gitea_resolved_version: "{{ (gitea_version_json.content | from_json).latest.version }}"
when: gitea_version == ""
- name: 使用指定版本号
set_fact:
gitea_resolved_version: "{{ gitea_version }}"
when: gitea_version != ""
- name: 显示将要安装的 Gitea 版本
debug:
msg: "将安装 Gitea {{ gitea_resolved_version }}"
- name: 检查 Gitea 是否已安装
stat:
path: /usr/local/bin/gitea
register: gitea_binary
- name: 获取已安装的 Gitea 版本
command: /usr/local/bin/gitea --version
register: gitea_installed_version
changed_when: false
failed_when: false
when: gitea_binary.stat.exists
- name: 下载 Gitea 二进制文件
get_url:
url: "https://dl.gitea.com/gitea/{{ gitea_resolved_version }}/gitea-{{ gitea_resolved_version }}-linux-amd64"
dest: /usr/local/bin/gitea
mode: "0755"
force: yes
when: >
not gitea_binary.stat.exists or
gitea_resolved_version not in (gitea_installed_version.stdout | default(''))
notify: 重启 Gitea
-8
View File
@@ -1,8 +0,0 @@
---
# roles/gitea/tasks/main.yml
- name: 安装 Gitea
import_tasks: install.yml
- name: 配置 Gitea
import_tasks: configure.yml
-75
View File
@@ -1,75 +0,0 @@
; Gitea Configuration
; Managed by Ansible - DO NOT EDIT MANUALLY
APP_NAME = {{ gitea_app_name | default('同济大学高级语言程序设计答疑平台') }}
RUN_USER = git
RUN_MODE = prod
WORK_PATH = /var/lib/gitea
[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = {{ gitea_db_name }}
USER = {{ gitea_db_user }}
PASSWD = {{ gitea_db_password }}
SSL_MODE = disable
LOG_SQL = false
[server]
PROTOCOL = http
DOMAIN = {{ gitea_domain }}
HTTP_ADDR = {{ gitea_http_addr | default('0.0.0.0') }}
HTTP_PORT = {{ gitea_http_port }}
ROOT_URL = http://{{ gitea_domain }}:{{ gitea_http_port }}/
APP_DATA_PATH = /var/lib/gitea/data
LFS_START_SERVER = true
LFS_JWT_SECRET = {{ gitea_lfs_jwt_secret }}
[repository]
ROOT = /var/lib/gitea/data/gitea-repositories
DEFAULT_BRANCH = main
DEFAULT_REPO_UNITS = repo.code,repo.issues
DISABLE_STARS = true
[security]
INSTALL_LOCK = true
SECRET_KEY = {{ gitea_secret_key }}
INTERNAL_TOKEN = {{ gitea_internal_token }}
MIN_PASSWORD_LENGTH = 8
[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
ENABLE_NOTIFY_MAIL = false
DEFAULT_KEEP_EMAIL_PRIVATE = true
NO_REPLY_ADDRESS = noreply.{{ gitea_domain }}
[mailer]
ENABLED = false
[session]
PROVIDER = file
PROVIDER_CONFIG = /var/lib/gitea/data/sessions
[log]
ROOT_PATH = /var/lib/gitea/log
MODE = file
LEVEL = info
[webhook]
ALLOWED_HOST_LIST = {{ gitea_webhook_allowed_hosts | default('*') }}
SKIP_TLS_VERIFY = {{ gitea_webhook_skip_tls | default('false') }}
[api]
ENABLE_SWAGGER = true
MAX_RESPONSE_ITEMS = 100
[indexer]
ISSUE_INDEXER_PATH = /var/lib/gitea/data/indexers/issues.bleve
[picture]
DISABLE_GRAVATAR = true
[openid]
ENABLE_OPENID_SIGNIN = false
ENABLE_OPENID_SIGNUP = false
@@ -1,28 +0,0 @@
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
After=postgresql-{{ postgresql_version }}.service
[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
RestartSec=5s
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea
# Resource limits
LimitMEMLOCK=infinity
LimitNOFILE=65535
# Sandboxing
ProtectSystem=full
PrivateDevices=yes
PrivateTmp=yes
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
@@ -1,5 +0,0 @@
---
- name: 重启 PostgreSQL
systemd:
name: "postgresql-{{ postgresql_version }}"
state: restarted
-73
View File
@@ -1,73 +0,0 @@
---
# roles/postgresql/tasks/main.yml
# PostgreSQL 安装与配置
- name: 禁用系统自带的 postgresql 模块
command: dnf module disable postgresql -y
register: pg_module_disable
changed_when: "'Nothing to do' not in pg_module_disable.stdout"
failed_when: false
- name: 安装 PostgreSQL 官方仓库 RPM
dnf:
name: "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm"
state: present
disable_gpg_check: yes
- name: 安装 PostgreSQL {{ postgresql_version }}
dnf:
name:
- postgresql{{ postgresql_version }}-server
- postgresql{{ postgresql_version }}
- python3-psycopg2
state: present
- name: 检查 PostgreSQL 数据目录是否已初始化
stat:
path: "/var/lib/pgsql/{{ postgresql_version }}/data/PG_VERSION"
register: pg_data_dir
- name: 初始化 PostgreSQL 数据库集群
command: "/usr/pgsql-{{ postgresql_version }}/bin/postgresql-{{ postgresql_version }}-setup initdb"
when: not pg_data_dir.stat.exists
- name: 部署 pg_hba.conf
template:
src: pg_hba.conf.j2
dest: "/var/lib/pgsql/{{ postgresql_version }}/data/pg_hba.conf"
owner: postgres
group: postgres
mode: "0600"
notify: 重启 PostgreSQL
- name: 启用并启动 PostgreSQL 服务
systemd:
name: "postgresql-{{ postgresql_version }}"
state: started
enabled: yes
- name: 等待 PostgreSQL 就绪
wait_for:
port: 5432
delay: 2
timeout: 30
- name: 创建 Gitea 数据库用户
become: true
become_user: postgres
community.postgresql.postgresql_user:
name: "{{ gitea_db_user }}"
password: "{{ gitea_db_password }}"
state: present
no_log: true
- name: 创建 Gitea 数据库
become: true
become_user: postgres
community.postgresql.postgresql_db:
name: "{{ gitea_db_name }}"
owner: "{{ gitea_db_user }}"
encoding: UTF-8
lc_collate: en_US.UTF-8
lc_ctype: en_US.UTF-8
state: present
@@ -1,15 +0,0 @@
# PostgreSQL Client Authentication Configuration File
# ===================================================
# Managed by Ansible - DO NOT EDIT MANUALLY
# TYPE DATABASE USER ADDRESS METHOD
# "local" is for Unix domain socket connections only
local all postgres peer
local all all md5
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5
+379
View File
@@ -0,0 +1,379 @@
# TJHLP 定制(Gitea 客制化)
本目录存放课程答疑平台对 Gitea 的定制:**不改 Go 代码、不 fork、不重新编译**,
只通过 Gitea 官方的 `CustomPath` 覆盖机制 + `app.ini` 配置项来做。
- 首页从「一款极易搭建的自托管 Git 服务」改成答疑平台介绍
- 中文术语调整(Issue 不再译成「工单」等)
- 去掉 Gitea 的自我推销(页脚 Powered by、meta、docs.gitea.com 外链)
当前基线:**Gitea 1.27.3**(见 `gitea-version.txt`,需与 `deploy/.env` 的
`GITEA_VERSION` 保持一致)。
---
## 1. 调查结论(机制)
以下结论来自 1.27.3 源码与实机验证,不是猜测。
### 1.1 覆盖原理:CustomPath 分层文件系统
Gitea 把模板 / 语言 / 静态资源都编进了二进制,但读取时走 `assetfs.LayeredFS`:
**自定义层在前、内置层在后,同名文件自定义层优先**;不存在「部分合并」——
覆盖一个文件就是整份替换(`modules/assetfs/layered.go`)。
| 内容 | 自定义层路径 | 内置层 | 生效方式 |
| ------ | -------------- | -------- | ---------- |
| 页面模板 | `$CustomPath/templates/<相对路径>` | 二进制内 embed | 启动时编译,**重启生效** |
| 语言文件 | `$CustomPath/options/locale/locale_*.json` | 二进制内 embed | 启动时加载,dev 模式热加载 |
| 静态资源 | `$CustomPath/public/assets/**` | 二进制内 embed | 请求时读取,URL 前缀 `/assets/` |
| 其它数据 | `$CustomPath/options/{gitignore,label,license,readme}/...` | 二进制内 embed | 按需读取 |
> ★ **最容易踩的坑**:官方 Docker 镜像里 `GITEA_CUSTOM=/data/gitea`
> (`docker inspect` 可见),所以定制文件对应的是
> `/data/gitea/{templates,public,options}`,
> **不是** `/data/gitea/custom/...`。后者是「源码/二进制安装时
> `WorkPath/custom`」的习惯写法,在容器里挂了不会生效(实测无效)。
### 1.2 模板
- 落地页是 `templates/home.tmpl`;登录用户看到的是 Dashboard,落地页只对**未登录访客**
渲染(`routers/web/home.go`)。
- 想换首页有三种做法,成本从低到高:
1. **配置**:`[server] LANDING_PAGE = explore|organizations|login|/任意URL`
—— 直接不做落地页;
2. **模板**:覆盖 `custom/templates/home.tmpl`(本目录采用的做法);
3. 加导航/页脚链接不需要覆盖整文件,用 `custom/templates/custom/extra_links.tmpl`、
`extra_links_footer.tmpl`(内置就是空模板,属增量修改)。
- 模板在**启动时编译**:prod 下改完必须重启容器(官方文档同此说法)。
dev 模式会尝试热加载,但实测模板热加载不生效(语言文件可以),所以模板统一按
「改完重启」处理。
- 覆盖模板时**不要动 `{{...}}` 逻辑**,只改文案/图标/链接;上游升级后要 diff 回来。
### 1.3 中文翻译
- 1.27 起语言文件是 JSON(`options/locale/locale_zh-CN.json`,约 3900 个键)。
- 覆盖必须**整份文件**:非默认语言在加载时没有 en-US 兜底基座,而查不到键时会
**退回默认语言(英文)**,不是退回中文
(`modules/translation/translation.go`、`i18n/localestore.go`)。
只写几个键会导致整个界面大面积变英文。
- 因此本目录用 `build.py` 从**上游快照 + 我们的覆盖规则**确定性生成整份文件,
人只需要维护 `overrides/` 下那几十行(详见 §3)。
### 1.4 能用配置解决的,别动模板
| 目标 | 配置项(app.ini) | Docker 环境变量 |
| ------ | ----------------- | ----------------- |
| 站点名 | 顶层 `APP_NAME` | `APP_NAME`(裸变量,镜像模板用) |
| 首页指向 | `[server] LANDING_PAGE` | `GITEA__server__LANDING_PAGE` |
| meta 作者/描述/关键词 | `[ui.meta] AUTHOR/DESCRIPTION/KEYWORDS` | `GITEA__ui_0X2E_meta__DESCRIPTION` 等 |
| 页脚 Powered by / 版本号 | `[other] SHOW_FOOTER_POWERED_BY` / `SHOW_FOOTER_VERSION` | `GITEA__other__SHOW_FOOTER_POWERED_BY` |
| Issue 显示姓名而非学号 | `[ui] DEFAULT_SHOW_FULL_NAME` | `GITEA__ui__DEFAULT_SHOW_FULL_NAME` |
| 自定义主题配色 | `[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` 等 | 同上(文件方式) |
> 环境变量规则:`GITEA__<段名>__<键名>`,段名里的 `.` 不能直接写,要编码成
> `_0X2E_`,所以 `[ui.meta]` 是 `GITEA__ui_0X2E_meta__...`
> (`modules/setting/config_env.go`)。
### 1.5 选择顺序(重要)
改一个东西之前,按这个顺序选手段,维护成本递增:
1. **app.ini / 环境变量**(无文件、升级无感)
2. **`custom/templates/custom/extra_*.tmpl`**(增量追加,不覆盖上游文件)
3. **`custom/options/` 数据文件覆盖**(语言、labels…)
4. **整文件覆盖内置模板**(本目录的 `custom/templates/home.tmpl`、`base/head_navbar.tmpl`)
5. 自建镜像 / fork 改 Go 代码 —— 只有在需要改逻辑或前端资源时才考虑,本阶段不需要
---
## 2. 目录结构
```text
customization/
├── README.md 本文件
├── gitea-version.txt 基线版本(与 deploy/.env 的 GITEA_VERSION 同步)
├── build.py 生成 locale + 规范 custom/ 权限(容器用户要能读)
├── fetch-upstream.sh 拉取上游文件快照(升级时用)
├── upstream-files.txt 需要留快照的上游文件清单
├── upstream/<版本>/... 上游基线,只读参考,由脚本生成
├── overrides/ ★ 只维护这里
│ ├── locale_zh-CN.rules.json 批量字面替换(如「工单」→「Issue」)
│ └── locale_zh-CN.json 精确到键的覆盖(优先于 rules)
├── custom/ ★ 挂进容器的覆盖层(= $CustomPath 的内容)
│ ├── templates/home.tmpl 落地页
│ ├── templates/base/head_navbar.tmpl 导航栏(去掉 docs.gitea.com)
│ ├── 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
└── preview/ 本地预览(独立 compose,独立端口/数据)
├── compose.yaml
├── preview.sh
└── data/ 预览数据,已 gitignore
```
`custom/` 与 `$CustomPath` 的结构一一对应;`custom/options/locale/*.json` 是生成物,
**不要手改**(`build.py --check` 会检查是否与 overrides 一致)。
---
## 3. 改东西的日常流程
### 3.1 改中文翻译
只动 `overrides/`,然后重新生成:
```bash
# 批量术语: 改 overrides/locale_zh-CN.rules.json
# 个例精修: 改 overrides/locale_zh-CN.json(键必须在同版本上游存在,否则构建报错)
python3 customization/build.py # 会打印每一处改动
python3 customization/build.py --check # CI/部署前校验生成物是否最新
```
约定:
- `rules` 是字面替换,会自动在中英交界处补空格(`基于工单列表` → `基于 Issue 列表`);
- `overrides` 在 rules 之后应用,用来收拾生硬的地方(如 `<strong>%d</strong> 张工单`
→ `共 <strong>%d</strong> 个 Issue`);
- 含占位符(`%s`/`%[1]s`/`%d`)的条目会校验占位符是否被改坏,改坏直接构建失败;
- 覆盖键在上游不存在会报错 —— 这是升级时发现「上游删了/改了键名」的保护。
### 3.2 改页面
1. 先把上游基线 diff 一遍,确认结构没变:
`diff upstream/<版本>/templates/home.tmpl custom/templates/home.tmpl`
2. 在 `custom/templates/...` 里改文案/图标/链接;
3. 新增一个要覆盖的模板时,把它加进 `upstream-files.txt`,再跑
`customization/fetch-upstream.sh <版本>` 留下基线。
### 3.3 本地预览
```bash
customization/preview/preview.sh up # 启动,http://127.0.0.1:2081
customization/preview/preview.sh logs # 看日志
customization/preview/preview.sh reload # 改完模板/生成语言文件后重启
customization/preview/preview.sh check # 自动校验: 首页文案/页脚/meta/静态页/术语
customization/preview/preview.sh admin # 建管理员(验证登录后页面,如 Issue 列表)
customization/preview/preview.sh reset # 清空预览数据重新来
```
预览实例与生产完全隔离:项目名 `gitea-preview`、容器 `gitea-preview`、
端口只绑 `127.0.0.1:2081`、数据库用 sqlite、数据在 `preview/data/`(删掉即重置)。
用的是**与生产相同的镜像版本**,所以渲染结果一致。
- `RUN_MODE` 默认 `dev`:语言文件改动会自动热加载(实测),模板报错也不致命;
`PREVIEW_RUN_MODE=prod ./preview.sh up` 可切到与生产一致的严格模式。
- **模板改动仍需重启**(`reload`),这是 Gitea 的既有行为。
- 需要 docker 权限;当前 shell 不在 docker 组时脚本会自动改用 `sg docker -c`。
### 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.1 改动点(已在 `deploy/` 落地)
`deploy/compose.yaml` 的 `gitea` 服务增加了三行只读挂载(注意目标是
`/data/gitea/...`,不是 `/data/gitea/custom/...`),`deploy/.env` 与
`.env.example` 增加了 `GITEA_CUSTOM_DIR=../customization/custom`:
```yaml
volumes:
- ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data
# 定制覆盖层: 官方镜像 GITEA_CUSTOM=/data/gitea
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
```
`deploy/.env` 增加:
```ini
# 相对 deploy/ 目录解析; 也可写绝对路径
GITEA_CUSTOM_DIR=../customization/custom
```
再在 `gitea` 的 `environment:` 里补上去 Gitea 化的元信息(也可以只改 `APP_NAME`):
```yaml
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
GITEA__ui_0X2E_meta__DESCRIPTION: 同济大学高级语言程序设计课程答疑平台
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false"
# Issue 发布者/评论者显示姓名(导入时 full_name=姓名, login=学号)
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
```
设计取舍:
- **只读挂载**:定制内容是仓库里的源码,容器不应回写;`conf/`、`log/` 等仍在
`/data/gitea` 里由容器自己管理,互不影响。
- 挂三个子目录而不是整个 `custom/`:避免遮住同级的 `conf/`、`log/`。
- 镜像 entrypoint 会做 `chown -R git:git /data/gitea`,只在属主不是 `git` 时执行;
现有 `/srv/gitea/gitea` 属主已是 `git`(982),不会碰到只读挂载。
- 定制只影响渲染,**不碰数据库和仓库**,回滚 = 去掉挂载 + 重启。
### 4.2 与课程官网联动
课程官网(VitePress 项目 `tjhlp-website`,部署在同一台机器的 `https://cpp.tongji.sh/Website/`)
与答疑平台互为入口。平台侧已经落地的入口:
| 位置 | 内容 | 文件 |
| ------ | ------ | ------ |
| 导航栏(未登录) | 「课程官网」/「提问指南」 | `custom/templates/base/head_navbar.tmpl` |
| 用户菜单(已登录) | 「课程官网」/「提问指南」 | 同上 |
| 首页「按模板提问」卡片 | 官网《提问指南》 | `custom/templates/home.tmpl` |
| 首页底部「相关站点」 | 官网 / 提问指南 / 常见问题 / 联系我们 | 同上 |
| 首页答疑入口卡片 | 官网《提问指南》 | `custom/templates/custom/tjhlp_semester_card.tmpl` |
| 新建 Issue 页的引导链接 | 提问指南 / 课程官网 | `issue-templates/*/.gitea/ISSUE_TEMPLATE/config.yaml` |
官网地址 `https://cpp.tongji.sh/Website/` 出现在上表列出的模板与两个 `config.yaml` 里;
平台自身地址只在 `scripts/settings.toml` 的 `gitea.public_url` 里维护一处(Issue 模板里的
`{{BASE_URL}}` 在推送时替换)。
> **提问指南只在官网保留一份**(`/Website/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-linkage.md`](website-linkage.md)。
### 4.3 部署步骤
```bash
cd deploy
python3 ../customization/build.py # 1. 重新生成 + 规范 custom/ 权限(见下)
python3 ../customization/build.py --check # (可选)校验生成物与权限
./scripts/backup.sh # 2. 例行备份(内容定制其实不影响数据)
# 3. 应用 compose/.env 改动后(会重建容器)
docker compose up -d
# 只改了 custom/ 里的内容(无 compose 变化)时:
# docker compose restart gitea
sudo ./scripts/verify.sh # 4. 体检
curl -s https://cpp.tongji.sh/QA/ | grep -c 课程答疑平台 # 5. 抽查首页
```
> **⚠️ 权限坑(2026-09 生产真的挂过一次)**:`custom/` 是只读挂载,而容器里的 Gitea 以
> `git`(982)运行。编辑器/工具写出来的文件常是 `600`,只读挂载**不会**放宽权限检查,
> 启动时直接:
> ```text
> [F] Gitea can't run with template errors: open home.tmpl: permission denied
> ```
> 然后 `Restarting` 死循环。**预览环境不会暴露它** —— 预览容器的 uid 就是宿主用户
> (`PREVIEW_UID`),同一属主当然读得到。
> `build.py` 每次都会把 `custom/` 补齐成「组/其他人可读,目录可进入」,`--check` 也会在
> 不可读时报错退出,所以**部署前跑一次 `build.py` 就不会中招**。
> 手工体检:`docker compose exec -T -u git gitea head -c1 /data/gitea/templates/home.tmpl`。
回滚:去掉挂载与环境变量 → `docker compose up -d`;或 `git revert` 本目录改动 →
`docker compose restart gitea`。
### 4.4 升级 Gitea 时的流程
```bash
# 1. 同步版本号: customization/gitea-version.txt 与 deploy/.env 的 GITEA_VERSION
# 2. 拉上游快照
customization/fetch-upstream.sh 1.28.0
# 3. 看上游改了什么,特别是我们整文件覆盖过的模板
git diff customization/upstream/
# 4. 把上游的结构性改动合并进 custom/templates/**.tmpl
# 5. 重新生成语言文件(上游新增的键会自动带进来)
python3 customization/build.py
# 6. 预览验证
customization/preview/preview.sh up && customization/preview/preview.sh check
# 7. 备份 + 升级(与 deploy/README.md §7.1 一致)
cd deploy && ./scripts/backup.sh --quiesce && docker compose pull gitea && docker compose up -d gitea
```
`build.py` 会在「我们覆盖的键在新版本里不存在」「占位符对不上」时直接失败,
把升级风险挡在部署之前。
---
## 5. 已验证 / 未覆盖
已在本机实测(官方 1.27.3 镜像 + 独立预览实例):
- ✅ 落地页替换为定制 `home.tmpl`(4 张卡片、无 Gitea 功能介绍)
- ✅ `[ui.meta]` 元信息替换(`GITEA__ui_0X2E_meta__*` 编码有效)
- ✅ 页脚 Powered by / 版本号可关闭
- ✅ 导航栏 `docs.gitea.com` 外链替换为官网《提问指南》(`/Website/qa/ask/`)
- ✅ 平台内 `public/assets/tjhlp/ask-guide.html` 已删除, 页面与 Issue 模板全部指向官网
- ✅ zh-CN 整份覆盖后,仓库 Issue 页显示「创建 Issue / 前往 Issue」,不再出现「工单」
- ✅ 语言文件在 dev 模式下改动即生效(模板仍须重启)
- ✅ 登录页改成「统一身份认证」优先 + 「管理员登录」卡片,表单仍可正常登录/报错
- ✅ 关闭 `ENABLE_PASSKEY_AUTHENTICATION` 后,登录页不再出现空的通行密钥方框
- ✅ 首页(登录后)顶部出现学期答疑入口卡片: 只认 `tjhlp-<5 位数字>`、取最新学期、
无匹配则不显示(预览里用 3 个用户 × 4 个组织验证过)
- ✅ 打开 `[ui] DEFAULT_SHOW_FULL_NAME` 后, Issue 的「由 X 创建」与正文/评论作者
显示 `full_name`(姓名), 未填姓名的用户回退显示 login(学号)(预览实测)
尚未覆盖(需要时按同样套路加):
- Logo / favicon 换成本课程的图(需要设计稿;放到 `custom/public/assets/img/`)
- 注册页(`user/auth/signup.tmpl`)、错误页文案
- 更多术语(合并请求 / 仓库 / 里程碑…)—— 在 `overrides/` 里加规则即可
- 自定义主题配色(`[ui] THEMES` + `custom/public/assets/css/theme-*.css`)
+210
View File
@@ -0,0 +1,210 @@
#!/usr/bin/env python3
"""生成 TJHLP 定制用的 Gitea 简体中文语言文件。
Gitea 只支持「整个文件覆盖」locale: 放在 custom/options/locale/locale_zh-CN.json 的
文件会完全替换内置的 zh-CN。缺失的键不会退回中文, 而是退回默认语言(en-US),
所以覆盖文件必须是完整的一份, 不能只写改动项。本脚本用来从上游快照
(upstream/<版本>/locale_zh-CN.json) + 我们的覆盖(rules / overrides)确定性地产出
这份完整文件, 避免手工维护 3900 个键。
用法:
python3 customization/build.py # 生成 custom/options/locale/locale_zh-CN.json
python3 customization/build.py --check # 只校验磁盘上的生成物是否最新(CI / 部署前)
python3 customization/build.py --quiet # 不打印改动清单
除了生成语言文件, 本脚本还负责把 custom/ 的权限规范成「容器用户可读」——
Gitea 容器以镜像内的 git 用户运行, 而编辑器写出来的文件可能是 600, 只读挂载进容器后
会 permission denied 并让 Gitea 拒绝启动(见 deploy/README.md 已知陷阱 3)。
"""
from __future__ import annotations
import argparse
import json
import re
import stat
import sys
from pathlib import Path
HERE = Path(__file__).resolve().parent
CUSTOM_DIR = HERE / "custom"
OUT_PATH = CUSTOM_DIR / "options" / "locale" / "locale_zh-CN.json"
# Go 模板/printf 里的格式化占位符, 例如 %s %d %v %[1]s %[2]d %%
FORMAT_RE = re.compile(r"%(?:\[(\d+)\])?[-+# 0-9.]*[a-zA-Z%]")
def load_json(path: Path):
with path.open(encoding="utf-8") as f:
return json.load(f)
def strip_comments(obj: dict) -> dict:
"""去掉以 _ 开头的说明键, 它们只是给人看的元数据。"""
return {k: v for k, v in obj.items() if not k.startswith("_")}
def format_verbs(text: str) -> list[str]:
return FORMAT_RE.findall(text)
def _is_cjk_ideograph(ch: str) -> bool:
# 只在汉字旁边补空格; 中文标点(。,、「」…)本身不需要与英文分隔
return "\u4e00" <= ch <= "\u9fff"
def _pad_for(edge: str, neighbour: str) -> str:
"""中英混排时给替换结果补一个空格: 汉字紧邻英文/数字才需要。"""
if edge and edge[0].isascii() and edge[0].isalnum() and neighbour and _is_cjk_ideograph(neighbour):
return " "
return ""
def apply_rule(text: str, src: str, dst: str) -> str:
"""字面替换 src -> dst, 并在中英交界处补空格(工单 -> " Issue ")。"""
out: list[str] = []
pos = 0
while True:
found = text.find(src, pos)
if found < 0:
out.append(text[pos:])
return "".join(out)
out.append(text[pos:found])
left = text[found - 1] if found > 0 else ""
right = text[found + len(src)] if found + len(src) < len(text) else ""
out.append(_pad_for(dst, left) + dst + _pad_for(dst[::-1], right))
pos = found + len(src)
def build() -> tuple[dict, dict, list[tuple[str, str, str]]]:
version = (HERE / "gitea-version.txt").read_text(encoding="utf-8").strip()
upstream_path = HERE / "upstream" / version / "options" / "locale" / "locale_zh-CN.json"
if not upstream_path.exists():
sys.exit(f"缺少上游快照: {upstream_path} (先执行 customization/fetch-upstream.sh {version})")
upstream: dict[str, object] = load_json(upstream_path)
locale: dict[str, object] = dict(upstream)
rules = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.rules.json"))["rules"]
overrides = strip_comments(load_json(HERE / "overrides" / "locale_zh-CN.json"))["overrides"]
errors: list[str] = []
for rule in rules:
src, dst = rule["from"], rule["to"]
for key, value in locale.items():
if isinstance(value, str) and src in value:
locale[key] = apply_rule(value, src, dst)
for key, new_value in overrides.items():
if key not in upstream:
errors.append(f"覆盖键不存在于上游: {key}")
continue
old_value = upstream[key]
if not isinstance(old_value, str):
errors.append(f"覆盖键在上游不是字符串: {key}")
continue
if format_verbs(old_value) != format_verbs(new_value):
errors.append(f"占位符不一致: {key}\n 上游: {old_value}\n 覆盖: {new_value}")
locale[key] = new_value
if errors:
sys.exit("构建失败:\n - " + "\n - ".join(errors))
changes = [(k, str(upstream[k]), str(v)) for k, v in locale.items() if upstream.get(k) != v]
return locale, upstream, changes
def render(locale: dict) -> str:
# 保持上游的键顺序, 让 git diff 只显示真正改动的行
return json.dumps(locale, ensure_ascii=False, indent=2) + "\n"
# ---------------------------------------------------------------------------
# custom/ 的权限
# ---------------------------------------------------------------------------
# Gitea 容器以镜像内的 git 用户运行(部署里 USER_UID=982), 而编辑器/工具写出来的文件
# 可能是 600(仅属主可读)。custom/ 是只读挂载进容器的, 一旦容器用户读不到,
# prod 模式会直接拒绝启动: "Gitea can't run with template errors: open home.tmpl:
# permission denied"(2026-09 生产真的这样挂过一次)。预览之所以没暴露, 是因为
# 预览容器的 uid 就是宿主用户。
# 所以每次生成都顺手把 custom/ 规范成「组 + 其他人可读, 目录可进入」。
def unreadable_paths(root: Path) -> list[Path]:
"""列出容器用户(非属主)读不到的文件/进不去的目录。"""
bad: list[Path] = []
for path in sorted(root.rglob("*")):
mode = path.stat().st_mode
need = stat.S_IROTH | (stat.S_IXOTH if path.is_dir() else 0)
if mode & need != need:
bad.append(path)
return bad
def ensure_readable(root: Path) -> list[Path]:
"""补齐 g+r / o+r(目录再补 o+x), 返回被修正的路径。"""
fixed: list[Path] = []
for path in sorted(root.rglob("*")):
mode = path.stat().st_mode
want = mode | stat.S_IRGRP | stat.S_IROTH
if path.is_dir():
want |= stat.S_IXGRP | stat.S_IXOTH
if want != mode:
path.chmod(want)
fixed.append(path)
return fixed
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--check", action="store_true", help="只校验, 不写入")
parser.add_argument("--quiet", action="store_true", help="不打印改动清单")
args = parser.parse_args()
locale, upstream, changes = build()
rendered = render(locale)
if not args.quiet:
print(f"上游键数: {len(upstream)} 覆盖后键数: {len(locale)} 改动: {len(changes)} 处")
for key, old, new in changes:
print(f" {key}\n - {old}\n + {new}")
if args.check:
current = OUT_PATH.read_text(encoding="utf-8") if OUT_PATH.exists() else ""
if current != rendered:
print(f"✗ {OUT_PATH} 与覆盖配置不一致, 请运行 python3 customization/build.py", file=sys.stderr)
return 1
print(f"✓ {OUT_PATH} 是最新的")
bad = unreadable_paths(CUSTOM_DIR)
if bad:
print(
"✗ 下列文件/目录对容器用户不可读(挂载进容器会 permission denied), "
"请运行 python3 customization/build.py 修正:",
file=sys.stderr,
)
for path in bad:
print(f" {path.relative_to(HERE)} {oct(path.stat().st_mode & 0o777)}", file=sys.stderr)
return 1
print("✓ custom/ 权限正常(容器用户可读)")
return 0
OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
try:
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}")
fixed = ensure_readable(CUSTOM_DIR)
if fixed:
print(f"✓ 修正了 {len(fixed)} 个权限过紧的路径(容器用户需要可读):")
for path in fixed:
print(f" {path.relative_to(HERE)}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
+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)。
@@ -0,0 +1,193 @@
{{/*
导航栏, 整文件覆盖 Gitea 内置 templates/base/head_navbar.tmpl。
相对上游只改了两处: 未登录时的「帮助」和用户菜单里的「帮助」指向课程提问指南,
不再外链 docs.gitea.com。上游基线见 upstream/<版本>/templates/base/head_navbar.tmpl,
升级时请 diff 该基线后重新合并, 不要直接覆盖本文件。
*/}}
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
<div class="navbar-left">
<!-- the logo -->
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
</a>
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
<div class="ui secondary menu navbar-mobile-right only-mobile">
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
</div>
<!-- navbar links non-mobile -->
{{if and .IsSigned .MustChangePassword}}
{{/* No links */}}
{{else if .IsSigned}}
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
{{end}}
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
{{end}}
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
{{if .ShowMilestonesDashboardPage}}
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
{{end}}
{{end}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{else if .IsLandingPageOrganizations}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
{{else}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{end}}
{{template "custom/extra_links" .}}
{{if not .IsSigned}}
<a class="item" href="https://cpp.tongji.sh/Website/">课程官网</a>
<a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a>
{{end}}
</div>
<!-- the full dropdown menus -->
<div class="navbar-right">
{{if and .IsSigned .MustChangePassword}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else if .IsSigned}}
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
<span class="flex-text-block">
{{svg "octicon-plus"}}
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
</span>
<div class="menu">
<a class="item" href="{{AppSubUrl}}/repo/create">
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
</a>
{{if not .DisableMigrations}}
<a class="item" href="{{AppSubUrl}}/repo/migrate">
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
</a>
{{end}}
{{if .SignedUser.CanCreateOrganization}}
<a class="item" href="{{AppSubUrl}}/org/create">
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
</a>
{{end}}
</div><!-- end content create new menu -->
</div><!-- end dropdown menu create new -->
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text tw-flex tw-items-center">
<span class="navbar-avatar">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
</span>
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{.SignedUser.HomeLink}}">
{{svg "octicon-person"}}
{{ctx.Locale.Tr "your_profile"}}
</a>
{{if not .DisableStars}}
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
{{svg "octicon-star"}}
{{ctx.Locale.Tr "your_starred"}}
</a>
{{end}}
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
{{svg "octicon-bell"}}
{{ctx.Locale.Tr "notification.subscriptions"}}
</a>
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
{{svg "octicon-tools"}}
{{ctx.Locale.Tr "your_settings"}}
</a>
<a class="item" href="https://cpp.tongji.sh/Website/qa/ask/">
{{svg "octicon-question"}}
提问指南
</a>
<a class="item" href="https://cpp.tongji.sh/Website/">
{{svg "octicon-book"}}
课程官网
</a>
{{if .IsAdmin}}
<div class="divider"></div>
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
{{svg "octicon-server"}}
{{ctx.Locale.Tr "admin_panel"}}
</a>
{{end}}
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else}}
{{if .ShowRegistrationButton}}
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
{{svg "octicon-person"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
</a>
{{end}}
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
{{svg "octicon-sign-in"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
</a>
{{end}}
</div><!-- end full right menu -->
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
{{if $activeStopwatch}}
<div class="active-stopwatch-popup tippy-target">
<div class="flex-text-block tw-p-3">
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
{{svg "octicon-issue-opened" 16}}
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
</a>
<div class="tw-flex tw-gap-1">
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
>{{svg "octicon-square-fill"}}</button>
</form>
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
>{{svg "octicon-trash"}}</button>
</form>
</div>
</div>
</div>
{{end}}
</nav>
{{template "base/head_banner"}}
@@ -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}}
+83
View File
@@ -0,0 +1,83 @@
{{/*
首页落地页, 整文件覆盖 Gitea 内置 templates/home.tmpl。
维护约定:
* 上游基线: customization/upstream/<版本>/templates/home.tmpl
升级 Gitea 时先 diff 基线, 把上游的结构性改动合并回来, 再重做文案。
* 文案直接写中文(平台只面向中文用户), 不复用 Gitea 的 startpage.* 文案,
这样首页不再出现「一款极易搭建的自托管 Git 服务」之类的自我推销。
* 只改文案/图标/链接, 保留原有 class 与结构, 避免升级后样式失效。
* 课程官网地址 https://cpp.tongji.sh/Website/ 出现在本文件、base/head_navbar.tmpl、
custom/tjhlp_semester_card.tmpl 以及 issue-templates 下两个 config.yaml 里,
换域名/路径时这几处要一起改(见 customization/README.md「与官网联动」)。
提问指南只在官网存一份: /Website/qa/ask/ —— 平台内不再保留副本(2026-09 起)。
*/}}
{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
<div class="tw-mb-8 tw-px-8">
<div class="center">
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{AppName}}">
<div class="hero">
<h1 class="ui icon header title tw-text-balance">
{{AppName}}
</h1>
<h2 class="tw-text-balance">同济大学高级语言程序设计课程答疑平台</h2>
</div>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-search"}} 先搜索,再提问
</h1>
<p class="large tw-text-balance">
大部分问题同学已经问过。提问前请先在
<a href="{{AppSubUrl}}/explore/repos">课程答疑仓库</a>
的 Issue 列表里搜索关键词,避免重复提问。
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-checklist"}} 按模板提问
</h1>
<p class="large tw-text-balance">
新建 Issue 时请选择合适的模板,写清题号、相关代码、报错信息和已经尝试过的做法。
提问规范与具体做法见课程官网的
<a href="https://cpp.tongji.sh/Website/qa/ask/">《提问指南》</a>。
</p>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-repo"}} 浏览课程仓库
</h1>
<p class="large tw-text-balance">
一般性问题放在 <code>general</code> 仓库,各次作业的问题放在对应的 <code>hwNN</code> 仓库,
可在<a href="{{AppSubUrl}}/explore/repos">仓库列表</a>中查看。
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-comment-discussion"}} 助教在线答疑
</h1>
<p class="large tw-text-balance">
助教会通过 Issue 回复,并用标签标记重复、已解决、待补充信息等问题。
问题解决后请回复确认,便于我们归档。
</p>
</div>
</div>
<div class="ui center aligned basic segment tw-px-8">
<p class="large">
相关站点:
<a href="https://cpp.tongji.sh/Website/">课程官网</a> ·
<a href="https://cpp.tongji.sh/Website/qa/ask/">提问指南</a> ·
<a href="https://cpp.tongji.sh/Website/qa/faq/">常见问题</a> ·
<a href="https://cpp.tongji.sh/Website/contact.html">联系我们</a>
</p>
<p>
<small>本平台只用于课程答疑,课程通知、作业要求等以课程官网与课程群为准。</small>
</p>
</div>
</div>
{{template "base/footer" .}}
@@ -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" .}}
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
# 拉取指定 Gitea 版本的上游文件快照到 upstream/<版本>/。
#
# 快照是定制构建的基线: build.py 由它 + overrides/ 生成最终 locale;
# templates/ 下我们整文件覆盖的模板也以它为 diff 依据。
#
# 用法:
# customization/fetch-upstream.sh 1.27.3
#
# 只下载源码包并抽取 upstream-files.txt 列出的文件, 不会保存整份源码。
set -euo pipefail
VERSION="${1:?用法: fetch-upstream.sh <版本, 例如 1.27.3>}"
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DEST="${HERE}/upstream/${VERSION}"
URL="https://dl.gitea.com/gitea/${VERSION}/gitea-src-${VERSION}.tar.gz"
TMP="$(mktemp -d)"
trap 'rm -rf "${TMP}"' EXIT
echo "下载 ${URL}"
curl -fsSL -o "${TMP}/src.tar.gz" "${URL}"
mkdir -p "${DEST}"
while read -r path; do
[ -z "${path}" ] && continue
case "${path}" in \#*) continue ;; esac
if ! tar -xzf "${TMP}/src.tar.gz" -C "${TMP}" "gitea-src-${VERSION}/${path}" 2>/dev/null; then
echo "✗ 上游不存在该文件(版本里改名/删除了?): ${path}" >&2
exit 1
fi
mkdir -p "${DEST}/$(dirname "${path}")"
cp "${TMP}/gitea-src-${VERSION}/${path}" "${DEST}/${path}"
echo " ✓ ${path}"
done <"${HERE}/upstream-files.txt"
echo "✓ 快照已更新到 ${DEST}"
echo " 下一步: python3 customization/build.py, 然后 diff 上游模板改动"
+1
View File
@@ -0,0 +1 @@
1.27.3
+16
View File
@@ -0,0 +1,16 @@
{
"_comment": [
"精确覆盖: 键名必须存在于同版本上游 locale_zh-CN.json, 否则构建报错。",
"在 rules 之后应用, 因此这里写的内容一定是最终结果。",
"改动前请对照上游原文; 含占位符(如 %s / %[1]s / %d / <strong>%d</strong>)的条目必须保留占位符。"
],
"overrides": {
"repo.activity.active_issues_count_1": "共 <strong>%d</strong> 个 Issue",
"repo.activity.active_issues_count_n": "共 <strong>%d</strong> 个 Issue",
"repo.activity.title.issues_1": "%d 个 Issue",
"repo.activity.title.issues_n": "%d 个 Issue",
"repo.milestones.filter_sort.most_issues": "按 Issue 数量从多到少",
"repo.milestones.filter_sort.least_issues": "按 Issue 数量从少到多",
"admin.repos.issues": "Issue 数"
}
}
@@ -0,0 +1,14 @@
{
"_comment": [
"按顺序对所有 zh-CN 译文做字面替换的规则。",
"适合「全站统一术语」这类批量修改, 新增术语时在这里加一条即可。",
"替换按数组顺序依次执行; 需要精修的具体条目请放到 locale_zh-CN.json(精确覆盖优先于本文件)。"
],
"rules": [
{
"note": "Issue 不译为「工单」, 直接沿用英文",
"from": "工单",
"to": "Issue"
}
]
}
+115
View File
@@ -0,0 +1,115 @@
# =============================================================================
# TJHLP 定制预览实例(与生产完全隔离, 只绑定回环)
#
# 目的: 在不动生产容器/数据的前提下, 用【与生产相同版本】的官方镜像验证
# customization/custom 下的模板、文案、静态资源效果。
#
# 与生产(deploy/compose.yaml)的区别:
# * 项目名 gitea-preview, 容器名 gitea-preview, 端口 127.0.0.1:2081
# * 数据库用 sqlite(预览不需要 PostgreSQL)
# * 数据目录 preview/data(gitignore), 删除即重置
# * RUN_MODE=dev: 修改 custom/ 下的模板或语言文件后自动热加载, 无需重启
# * 把 customization/custom 只读挂载到容器的 GITEA_CUSTOM/custom
#
# 用法(见 preview.sh):
# ./preview.sh up 启动
# ./preview.sh logs 看日志
# ./preview.sh down 停止
# ./preview.sh reset 停止并清空预览数据
# =============================================================================
name: gitea-preview
services:
gitea:
image: docker.gitea.com/gitea:${GITEA_VERSION:-1.27.3}
container_name: gitea-preview
restart: unless-stopped
environment:
# 与宿主当前用户对齐, 让 ./data 的属主正确(见 preview.sh)
USER_UID: ${PREVIEW_UID:-1001}
USER_GID: ${PREVIEW_GID:-1001}
TZ: ${TZ:-Asia/Shanghai}
APP_NAME: 同济高程-答疑平台(预览)
# dev(默认): 语言文件改动自动热加载(实测), 模板报错也不致命 —— 改文案方便;
# prod: 与生产完全一致, 任何改动都要 ./preview.sh reload。
# 注意: 模板是启动时编译的, dev 下改模板同样要重启(官方文档也是这么说的)。
RUN_MODE: ${PREVIEW_RUN_MODE:-dev}
# --- 数据库: sqlite(预览专用) -------------------------------------
GITEA__database__DB_TYPE: sqlite3
GITEA__database__PATH: /data/gitea/gitea.db
# --- 服务地址 ------------------------------------------------------
GITEA__server__PROTOCOL: http
GITEA__server__DOMAIN: 127.0.0.1
GITEA__server__ROOT_URL: http://127.0.0.1:${PREVIEW_PORT:-2081}/
GITEA__server__HTTP_ADDR: 0.0.0.0
GITEA__server__HTTP_PORT: "3000"
GITEA__server__DISABLE_SSH: "true"
GITEA__server__LFS_START_SERVER: "true"
GITEA__server__OFFLINE_MODE: "false"
# --- 安全: 跳过安装向导; 密钥不在这里指定 -------------------------
# LFS_JWT_SECRET / INTERNAL_TOKEN / JWT_SECRET 留空时 Gitea 会自己生成
# 并写回 /data/gitea/conf/app.ini(可写), 重启后保持不变。
GITEA__security__INSTALL_LOCK: "true"
# --- 注册 / 登录 ---------------------------------------------------
GITEA__service__DISABLE_REGISTRATION: "false"
GITEA__service__ENABLE_CAPTCHA: "false"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
# 不做通行密钥(WebAuthn): 上游登录页那块只有 tw-hidden 元素, 浏览器不支持条件中介时
# 会留下一个空的方框; 关掉后区块不再渲染, 登录页也不会出现 passkey 入口。
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION: "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 自我推销 -------------------------
# 段名里的点要写成 _0X2E_ (Gitea 的 GITEA__section__KEY 编码规则)
GITEA__ui_0X2E_meta__AUTHOR: 同济大学高级语言程序设计课程
GITEA__ui_0X2E_meta__DESCRIPTION: 同济大学高级语言程序设计课程答疑平台
GITEA__ui_0X2E_meta__KEYWORDS: 同济大学,高级语言程序设计,答疑,Issue
GITEA__other__SHOW_FOOTER_POWERED_BY: "false"
GITEA__other__SHOW_FOOTER_VERSION: "false"
# --- 显示名称: 与生产一致, Issue 显示姓名而不是学号 ----------------
# 说明见 deploy/compose.yaml 同位置。这里给上才能让预览里验证
# 「发布者/回答者显示姓名」的效果。
GITEA__ui__DEFAULT_SHOW_FULL_NAME: "true"
GITEA__log__MODE: console
GITEA__log__LEVEL: ${GITEA_LOG_LEVEL:-info}
volumes:
- ./data:/data
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
# /data/gitea/{templates,public,options}, 而不是 /data/gitea/custom
# (后者是源码/二进制安装时 WorkPath/custom 的习惯写法)。
# 分开挂三个子目录: 既只读覆盖定制内容, 又不遮住同级的 conf/、log/。
- ../custom/templates:/data/gitea/templates:ro
- ../custom/public:/data/gitea/public:ro
- ../custom/options:/data/gitea/options:ro
- /etc/localtime:/etc/localtime:ro
ports:
# 只绑定回环, 预览实例不对内网/外网暴露
- "127.0.0.1:${PREVIEW_PORT:-2081}:3000"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
interval: 10s
timeout: 5s
retries: 10
start_period: 60s
+198
View File
@@ -0,0 +1,198 @@
#!/usr/bin/env bash
# 预览实例管理脚本: 见 compose.yaml 顶部说明。
#
# ./preview.sh up 构建定制产物并启动预览 (http://127.0.0.1:2081)
# ./preview.sh down 停止预览(保留数据)
# ./preview.sh reset 停止并删除预览数据(下次全新安装)
# ./preview.sh logs 跟踪日志
# ./preview.sh ps 查看状态
# ./preview.sh shell 进入容器
# ./preview.sh admin 在预览实例里建一个管理员(用于验证登录后的页面)
# ./preview.sh semester 造一个学期组织(含 general 仓库), 用于看首页的答疑入口卡片
# ./preview.sh check 构建校验 + 首页文案/页脚/元信息抽查
#
# 说明: 本机 docker 需要 docker 组权限; 当前 shell 没有时会自动改用
# `sg docker -c ...`(sg 读 /etc/group 的成员关系, 不需要 sudo)。
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ROOT="$(cd "${HERE}/.." && pwd)"
COMPOSE_FILE="${HERE}/compose.yaml"
PORT="${PREVIEW_PORT:-2081}"
BASE_URL="http://127.0.0.1:${PORT}"
export PREVIEW_UID="$(id -u)"
export PREVIEW_GID="$(id -g)"
# 是否需要套 sg docker
if docker info >/dev/null 2>&1; then
compose() { docker compose -f "${COMPOSE_FILE}" "$@"; }
elif command -v sg >/dev/null 2>&1 && sg docker -c 'docker info' >/dev/null 2>&1; then
compose() { sg docker -c "docker compose -f '${COMPOSE_FILE}' $*"; }
else
echo "✗ 当前用户没有 docker 权限(既不能直连, 也不能通过 docker 组)" >&2
exit 1
fi
prepare() {
# 生成定制产物(语言文件等)
python3 "${ROOT}/build.py" --quiet
# 预建数据目录: 属主等于当前用户, 容器 entrypoint 就不会对只读挂载做 chown。
# .ssh 必须由我们建: 否则容器以 root 建出 0700 目录, 降权后的 gitea 进程
# 写不了 authorized_keys。
mkdir -p "${HERE}/data/gitea/conf" "${HERE}/data/git/.ssh" "${HERE}/data/ssh"
chmod 700 "${HERE}/data/git/.ssh"
}
case "${1:-}" in
up)
prepare
compose up -d
echo "预览地址: ${BASE_URL} (数据目录: ${HERE}/data)"
echo "首次启动约需 10~30 秒; 用 ./preview.sh logs 观察进度"
;;
down)
compose down
;;
reload)
# 模板改完必须重启才生效(prod/dev 都一样); 语言文件在 dev 下会自动热加载
python3 "${ROOT}/build.py" --quiet
compose restart gitea
echo "已重启, 预览地址: ${BASE_URL}"
;;
reset)
compose down
if ! rm -rf "${HERE}/data" 2>/dev/null; then
# 容器可能以 root 身份建过 data/git/.ssh(0700), 宿主用户删不掉;
# 用一次性 root 容器清掉再删(正常流程不会走到这里, 见 prepare 的说明)。
compose run --rm -T --user 0 --entrypoint /bin/sh gitea -c 'rm -rf /data/git /data/ssh' >/dev/null
rm -rf "${HERE}/data"
fi
echo "已清空预览数据"
;;
logs)
compose logs -f --tail=100
;;
ps)
compose ps
;;
shell)
compose exec gitea bash
;;
admin)
USERNAME="${2:-previewadmin}"
PASSWORD="${3:-previewadmin123}"
# -u git: gitea 命令拒绝以 root 运行
compose exec -T -u git gitea gitea admin user create \
--username "${USERNAME}" --password "${PASSWORD}" \
--email "${USERNAME}@example.com" --admin --must-change-password=false
echo "管理员: ${USERNAME} / ${PASSWORD}"
;;
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)
python3 "${ROOT}/build.py" --check --quiet
fail=0
ok() { echo "✓ $1"; }
bad() {
echo "✗ $1"
fail=1
}
html="$(mktemp)"
trap 'rm -f "${html}"' EXIT
curl -fsS "${BASE_URL}/" -o "${html}"
grep -q "先搜索,再提问" "${html}" && ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
ok "导航栏/首页已指向官网提问指南(/Website/qa/ask/)" ||
bad "没找到官网提问指南链接(页面还是旧模板? 模板改动要重启 gitea 才生效)"
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${html}" &&
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
! grep -qi "powered by" "${html}" && ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
! grep -q "docs.gitea.com" "${html}" && ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${html}" &&
ok "meta description 已替换" || bad "meta description 未替换"
# 站内提问指南页已按决定删除(提问指南只在官网保留一份)
! curl -fsS -o /dev/null "${BASE_URL}/assets/tjhlp/ask-guide.html" 2>/dev/null &&
ok "平台内提问指南页已删除" || bad "平台内还留着 ask-guide.html"
# --- 与课程官网的联动 -------------------------------------------------
grep -q "https://cpp.tongji.sh/Website/" "${html}" &&
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
grep -q "https://cpp.tongji.sh/Website/qa/ask/" "${html}" &&
ok "首页已链接官网提问指南" || bad "首页没有官网提问指南链接"
! grep -q "Website/ask-question/\|Website/faq/\|Website/contact\"" "${html}" &&
ok "没有指向官网已迁移/失效的旧地址" ||
bad "仍有旧地址(ask-question / faq / contact 无 .html)"
! grep -rq "example.com" "${ROOT}/../issue-templates/" &&
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" &&
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
# --- 登录页 -----------------------------------------------------------
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 "存在检查未通过项"
exit "${fail}"
;;
*)
sed -n '2,18p' "$0"
exit 1
;;
esac
+11
View File
@@ -0,0 +1,11 @@
# 需要留快照的上游文件(相对 gitea 源码根目录), 每行一个, # 开头为注释。
#
# 什么时候往这里加一行:
# * build.py 生成的 locale 基线(必须)
# * custom/templates/ 下我们整文件覆盖的内置模板(必须, 否则升级时没有 diff 依据)
# * custom/options/ 下我们覆盖的内置数据文件(如 gitignore/label)
options/locale/locale_zh-CN.json
templates/home.tmpl
templates/base/head_navbar.tmpl
templates/user/auth/signin.tmpl
templates/user/dashboard/dashboard.tmpl
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,182 @@
<nav id="navbar" aria-label="{{ctx.Locale.Tr "aria.navbar"}}">
<div class="navbar-left">
<!-- the logo -->
<a class="item" id="navbar-logo" href="{{AppSubUrl}}/" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}">
<img width="30" height="30" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}" aria-hidden="true">
</a>
<!-- mobile right menu, it must be here because in mobile view, each item is a flex column, the first item is a full row column -->
<div class="ui secondary menu navbar-mobile-right only-mobile">
{{template "base/head_navbar_icons" dict "PageGlobalData" .PageGlobalData}}
<button class="item ui icon mini button tw-m-0" id="navbar-expand-toggle" aria-label="{{ctx.Locale.Tr "home.nav_menu"}}">{{svg "octicon-three-bars"}}</button>
</div>
<!-- navbar links non-mobile -->
{{if and .IsSigned .MustChangePassword}}
{{/* No links */}}
{{else if .IsSigned}}
{{if not ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled}}
<a class="item{{if .PageIsIssues}} active{{end}}" href="{{AppSubUrl}}/issues">{{ctx.Locale.Tr "issues"}}</a>
{{end}}
{{if not ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled}}
<a class="item{{if .PageIsPulls}} active{{end}}" href="{{AppSubUrl}}/pulls">{{ctx.Locale.Tr "pull_requests"}}</a>
{{end}}
{{if not (and ctx.Consts.RepoUnitTypeIssues.UnitGlobalDisabled ctx.Consts.RepoUnitTypePullRequests.UnitGlobalDisabled)}}
{{if .ShowMilestonesDashboardPage}}
<a class="item{{if .PageIsMilestonesDashboard}} active{{end}}" href="{{AppSubUrl}}/milestones">{{ctx.Locale.Tr "milestones"}}</a>
{{end}}
{{end}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{else if .IsLandingPageOrganizations}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/organizations">{{ctx.Locale.Tr "explore_title"}}</a>
{{else}}
<a class="item{{if .PageIsExplore}} active{{end}}" href="{{AppSubUrl}}/explore/repos">{{ctx.Locale.Tr "explore_title"}}</a>
{{end}}
{{template "custom/extra_links" .}}
{{if not .IsSigned}}
<a class="item" target="_blank" href="https://docs.gitea.com">{{ctx.Locale.Tr "help"}}</a>
{{end}}
</div>
<!-- the full dropdown menus -->
<div class="navbar-right">
{{if and .IsSigned .MustChangePassword}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-1"}}
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else if .IsSigned}}
{{template "base/head_navbar_icons" dict "ItemExtraClass" "not-mobile" "PageGlobalData" .PageGlobalData}}
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "create_new"}}">
<span class="flex-text-block">
{{svg "octicon-plus"}}
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
<span class="only-mobile">{{ctx.Locale.Tr "create_new"}}</span>
</span>
<div class="menu">
<a class="item" href="{{AppSubUrl}}/repo/create">
{{svg "octicon-plus"}} {{ctx.Locale.Tr "new_repo"}}
</a>
{{if not .DisableMigrations}}
<a class="item" href="{{AppSubUrl}}/repo/migrate">
{{svg "octicon-repo-push"}} {{ctx.Locale.Tr "new_migrate"}}
</a>
{{end}}
{{if .SignedUser.CanCreateOrganization}}
<a class="item" href="{{AppSubUrl}}/org/create">
{{svg "octicon-organization"}} {{ctx.Locale.Tr "new_org"}}
</a>
{{end}}
</div><!-- end content create new menu -->
</div><!-- end dropdown menu create new -->
<div class="ui dropdown jump item" data-tooltip-content="{{ctx.Locale.Tr "user_profile_and_more"}}">
<span class="text tw-flex tw-items-center">
<span class="navbar-avatar">
{{ctx.AvatarUtils.Avatar .SignedUser 24 "tw-mr-2"}}
{{if .IsAdmin}}{{svg "octicon-shield-check" 16 "navbar-admin-badge"}}{{end}}
</span>
<span class="only-mobile">{{.SignedUser.Name}}</span>
<span class="not-mobile flex-text-block">{{svg "octicon-triangle-down"}}</span>
</span>
<div class="menu user-menu">
<div class="header">
{{ctx.Locale.Tr "signed_in_as"}} <strong>{{.SignedUser.Name}}</strong>
</div>
<div class="divider"></div>
<a class="item" href="{{.SignedUser.HomeLink}}">
{{svg "octicon-person"}}
{{ctx.Locale.Tr "your_profile"}}
</a>
{{if not .DisableStars}}
<a class="item" href="{{.SignedUser.HomeLink}}?tab=stars">
{{svg "octicon-star"}}
{{ctx.Locale.Tr "your_starred"}}
</a>
{{end}}
<a class="item" href="{{AppSubUrl}}/notifications/subscriptions">
{{svg "octicon-bell"}}
{{ctx.Locale.Tr "notification.subscriptions"}}
</a>
<a class="{{if .PageIsUserSettings}}active {{end}}item" href="{{AppSubUrl}}/user/settings">
{{svg "octicon-tools"}}
{{ctx.Locale.Tr "your_settings"}}
</a>
<a class="item" target="_blank" href="https://docs.gitea.com">
{{svg "octicon-question"}}
{{ctx.Locale.Tr "help"}}
</a>
{{if .IsAdmin}}
<div class="divider"></div>
<a class="{{if .PageIsAdmin}}active {{end}}item" href="{{AppSubUrl}}/-/admin">
{{svg "octicon-server"}}
{{ctx.Locale.Tr "admin_panel"}}
</a>
{{end}}
<div class="divider"></div>
<a class="item" href="{{AppSubUrl}}/user/logout">
{{svg "octicon-sign-out"}}
{{ctx.Locale.Tr "sign_out"}}
</a>
</div><!-- end content avatar menu -->
</div><!-- end dropdown avatar menu -->
{{else}}
{{if .ShowRegistrationButton}}
<a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">
{{svg "octicon-person"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "register"}}</span>
</a>
{{end}}
<a class="item{{if .PageIsSignIn}} active{{end}}" rel="nofollow" href="{{AppSubUrl}}/user/login">
{{svg "octicon-sign-in"}}
<span class="tw-ml-1">{{ctx.Locale.Tr "sign_in"}}</span>
</a>
{{end}}
</div><!-- end full right menu -->
{{$activeStopwatch := and .PageGlobalData (call .PageGlobalData.GetActiveStopwatch)}}
{{if $activeStopwatch}}
<div class="active-stopwatch-popup tippy-target">
<div class="flex-text-block tw-p-3">
<a class="stopwatch-link flex-text-block muted" href="{{$activeStopwatch.IssueLink}}">
{{svg "octicon-issue-opened" 16}}
<span class="stopwatch-issue">{{$activeStopwatch.RepoSlug}}#{{$activeStopwatch.IssueIndex}}</span>
</a>
<div class="tw-flex tw-gap-1">
<form class="stopwatch-commit form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/stop">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.stop_tracking"}}"
>{{svg "octicon-square-fill"}}</button>
</form>
<form class="stopwatch-cancel form-fetch-action" method="post" action="{{$activeStopwatch.IssueLink}}/times/stopwatch/cancel">
<button
type="submit"
class="ui button mini compact basic icon tw-mr-0"
data-tooltip-content="{{ctx.Locale.Tr "repo.issues.cancel_tracking"}}"
>{{svg "octicon-trash"}}</button>
</form>
</div>
</div>
</div>
{{end}}
</nav>
{{template "base/head_banner"}}
@@ -0,0 +1,51 @@
{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home_title"}}{{end}}" class="page-content home">
<div class="tw-mb-8 tw-px-8">
<div class="center">
<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}">
<div class="hero">
<h1 class="ui icon header title tw-text-balance">
{{AppName}}
</h1>
<h2 class="tw-text-balance">{{ctx.Locale.Tr "startpage.app_desc"}}</h2>
</div>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-flame"}} {{ctx.Locale.Tr "startpage.install"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.install_desc" "https://docs.gitea.com/installation/install-from-binary" "https://github.com/go-gitea/gitea/tree/master/docker" "https://docs.gitea.com/installation/install-from-package"}}
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-device-desktop"}} {{ctx.Locale.Tr "startpage.platform"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.platform_desc" "https://go.dev/"}}
</p>
</div>
</div>
<div class="ui stackable middle very relaxed page grid">
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-rocket"}} {{ctx.Locale.Tr "startpage.lightweight"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.lightweight_desc"}}
</p>
</div>
<div class="eight wide center column">
<h1 class="hero ui icon header">
{{svg "octicon-code"}} {{ctx.Locale.Tr "startpage.license"}}
</h1>
<p class="large tw-text-balance">
{{ctx.Locale.Tr "startpage.license_desc" "https://gitea.dev" "gitea.dev" "https://github.com/go-gitea/gitea"}}
</p>
</div>
</div>
</div>
{{template "base/footer" .}}
@@ -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" .}}
+187
View File
@@ -0,0 +1,187 @@
# 官网 ↔ 答疑平台 联动方案(提案)
> 这份文档是**给 Website 仓库的改动提案**, 不涉及本仓库代码。
> 平台侧的入口已经落地(见 `README.md` 「4.2 与课程官网联动」), 本文只讲官网侧怎么接。
## 0. 事实与现状(已核实)
| 项 | 事实 |
| ---- | ---- |
| 官网仓库 | `https://github.com/Tongji-High-level-Language-Programming/Website.git`(`/home/ymy/tjhlp-website`) |
| 站点框架 | VitePress, `base: "/Website/"`, 构建命令 `pnpm docs:build` |
| 线上地址 | `https://cpp.tongji.sh/Website/`(Apache `DocumentRoot=/home/httpd/hlp-website`, `RedirectMatch ^/$ /Website/`) |
| 部署方式 | GitHub Actions: push 到 `main` → 构建 → 同时发 GitHub Pages 与该服务器(`rsync` 到 `/home/httpd/hlp-website/Website/`) |
| 答疑平台 | `https://cpp.tongji.sh/QA/`(同一台机器, Apache `ProxyPass /QA`) |
| 图片资产 | Git LFS(`.gitattributes`), 15 张 PR 截图都是 LFS 指针 |
| 现状 main | 已到 PR #54; `#52` 的分支 `oierxjn:docs/gitea-tut` 落后 5 个提交, 但可干净合并 |
**关于 base 的坑(已实测)**: VitePress 会给 Markdown 里以 `/` 开头的站内链接自动加上
`base`。部署产物里 `docs/ask-question/index.md` 的 `[本站 FAQ 页面](/faq/)` 生成的是
`href="/Website/faq/"`。所以**跨站链接不能写 `/QA/`**(会被改写成 `/Website/QA/`),
必须写完整 URL —— PR #52 里写完整 URL 是对的。
## 1. PR #52 现状
标题: *WIP: docs: Update Gitea tutorial and contact information with new references*(draft),
作者 `oierxjn`, 分支 `docs/gitea-tut`, 18 个文件 `+167 -1`:
- `docs/faq/gitea/index.md` + 15 张截图: 平台使用指南(登录、搜索、创建/关闭 Issue)
- `docs/.vitepress/config.mts`: 「常见问题」导航加下拉项「高程答疑平台」
- `docs/ask-question/index.md`: 正文加入平台入口
- `docs/contact.md`: 「QQ 群提问」→「答疑平台提问」
方向正确, 下面是可以补齐/修正的点。
## 2. 复查发现的问题
### P1 · 建议修掉
1. **`docs/faq/gitea/index.md` 没有文件末尾换行**(`\ No newline at end of file`)。
仓库有 prettier + lint-staged, 建议补上, 避免后续 diff 噪音。
2. **同页第一段主语写错**:「课程的答疑主要在…进行。**网站**仅限同济大学校园网或同济 VPN
访问。」—— 上一句主语是平台。建议改为「平台与本站均仅限校园网 / 同济 VPN 访问」。
3. **同页 `/contact.md` 链接**:`[联系团队](/contact.md)`。虽然 VitePress 能处理 `.md`
链接, 但站内其他地方(导航、侧栏)统一写 `/contact`, 建议一致; 该句还缺句号。
4. **旧组织名**:`docs/contact.md`(PR 改动行)与 `docs/.vitepress/config.mts` 的
`socialLinks` 都写成 `Tongji-High-level-Programming-Language`(词序颠倒)。实测该
地址目前 200 是因为 GitHub 的组织改名重定向, 建议改成当前组织名
`Tongji-High-level-Language-Programming`, 不要依赖重定向。
### P2 · 建议调整
5. **入口层级偏低**:目前只有「常见问题」下拉里的一个子项。建议在**顶部导航**加一个
一级「答疑平台」外链, 并在**首页 hero** 加一个 `答疑平台` 按钮 —— 这是学生最需要的入口。
6. **首页提示过期**:`docs/index.md` 底部 `::: danger` 写着「所有通知、作业等重要信息请以
官方课程 QQ 群为准」。既然答疑已迁到平台, 建议改为「以课程官网与答疑平台公告为准」,
并把 `学会提问`/`FAQ` 之外补上平台入口。
7. **`docs/faq/index.md` 没有平台入口**:FAQ 是学生最常翻的页面, 建议在顶部 tip 里直接
给出平台链接与《使用指南》。
8. **「为什么 Gitea 作为答疑平台?」整段引用了 Gitea 官方宣传文案**, 其中包含「极易安装…
自建 Git 服务」这种推销语, 与网站正文风格不符。建议只保留后半段「如你所见, Gitea 提供了
完整的 Issue 管理功能…」。
9. **账号开通方式待确认**:同页写「账号目前由管理员统一开通, 没有额外的注册入口」。如果
实际是统一身份认证(OIDC)首次登录自动建号, 这句会误导学生 —— 需要按实际流程改写。
### P3 · 后续
10. **截图会随定制上线而部分过期**:15 张截图拍摄于平台定制之前, 其中 `MainPage.png` 是
Gitea 默认落地页(「一款极易搭建的自托管 Git 服务」), 定制上线后平台首页已换成答疑
平台介绍; 若截图里出现过「工单」字样也与现在的 「Issue」不一致。建议定制上线后按同样
流程重拍、**文件名不变**地替换, 这样正文不用改。
11. **内容重复(已在平台侧处理完)**:官网提问指南与平台内的副本曾有重叠。2026-09 起
**提问指南只在官网保留一份**(`/Website/qa/ask/`), 平台内的
`/assets/tjhlp/ask-guide.html` 已删除, 平台页面与 Issue 模板的引导链接全部指向官网;
官网页因此不必再考虑与平台副本同步的问题。
> **2026-09 官网改版后的路径**:提问指南 `/Website/qa/ask/`、常见问题 `/Website/qa/faq/`、
> 联系我们 `/Website/contact.html`。旧的 `/Website/ask-question/`、`/Website/faq/` 已变成
> 跳转页, `/Website/contact` 已经 404。本文下面几节写于改版前, 里面的
> `/ask-question/`、`/contact.md` 等路径按新路径理解(PR #52 也要相应更新)。
## 3. 建议改动(可直接套用)
### 3.1 `docs/.vitepress/config.mts`
```ts
// 答疑平台(校内 Apache 反代 /QA)。外链必须写完整 URL:
// VitePress 会给以 / 开头的站内链接加上 base(/Website/), 写 /QA/ 会变成 /Website/QA/。
const QA_URL = "https://cpp.tongji.sh/QA/";
// themeConfig.nav —— 在「首页」之后插入一级入口
{ text: "答疑平台", link: QA_URL },
// 「常见问题」下拉保留(PR #52 已加)
{
text: "常见问题",
link: "/faq/",
items: [{ text: "答疑平台使用指南", link: "/faq/gitea/" }],
},
// themeConfig.sidebar —— 「学会提问」之后加一条(侧栏支持外链)
{ text: "答疑平台", link: QA_URL },
// socialLinks —— 顺手改成当前组织名
link: "https://github.com/Tongji-High-level-Language-Programming/Website",
```
### 3.2 `docs/index.md`
```yaml
actions:
- theme: brand
text: 课程信息
link: /syllabus/
- theme: brand
text: 答疑平台 # 新增
link: https://cpp.tongji.sh/QA/
- theme: alt
text: 学会提问
link: /ask-question/
- theme: alt
text: FAQ
link: /faq/
```
```md
::: danger 注意
本网站目前仍处于试运行状态,可能存在内容的缺失、错误或更新不及时。所有通知、作业等重要信息
请以课程官网与答疑平台的公告为准,课程群内也会同步。
:::
```
### 3.3 `docs/faq/index.md`
```md
::: tip
提问前请务必认真阅读 [学会提问](/ask-question/) 一文。课程答疑在
[高程答疑平台](https://cpp.tongji.sh/QA/) 上进行,使用方式见 [答疑平台使用指南](/faq/gitea/)。
:::
```
### 3.4 `docs/contact.md`
```md
本校同学的课程相关问题,请在 [高程答疑平台](https://cpp.tongji.sh/QA/) 提问
([使用指南](/faq/gitea/))
对本网站的意见与建议,可以直接提交
[GitHub Issue](https://github.com/Tongji-High-level-Language-Programming/Website/issues)
或者联系课程团队:
```
### 3.5 `docs/faq/gitea/index.md`
- 第一段:「平台与本站均仅限同济大学校园网或同济 VPN 访问。」
- `[联系团队](/contact.md)` → `[联系团队](/contact)`。
- 文末补一个换行。
- 「为什么 Gitea 作为答疑平台?」删掉官方宣传语的引用块, 保留后半段说明。
- 如按 §3.1 在导航加了入口, 页内可直接用 `[答疑平台](https://cpp.tongji.sh/QA/)`。
## 4. 落地与验证
```bash
cd ~/tjhlp-website
git lfs install # 截图是 LFS 对象, 缺了会构建出坏图
pnpm install
pnpm docs:dev # 本地预览: http://localhost:5173/Website/
pnpm docs:build # 站内死链会在构建期报错, 作为校验
```
- PR #52 的分支落后 main 5 个提交(可干净合并), 建议 `git rebase origin/main` 后继续,
或直接基于最新 main 重建分支; **截图是 LFS 对象, 不要用 patch 传递, 要用分支/PR 传**。
- 合并到 `main` 后由 GitHub Actions 自动 rsync 到 `/home/httpd/hlp-website/Website/`,
无需手工部署; 部署后可用 `curl -s https://cpp.tongji.sh/Website/ | grep 答疑平台` 抽查。
- 平台侧的对应入口已就绪(导航栏「课程官网」、首页「相关站点」、Issue 模板
`contact_links`), 两边合并后建议用 `customization/preview/preview.sh check` 复查。
## 5. 待确认
1. 平台对外地址长期是否就是 `https://cpp.tongji.sh/QA/`?若有域名计划, 建议官网只维护一个
常量(如上面的 `QA_URL`)。
2. 账号开通方式(管理员统一开通 / OIDC 首次登录自动注册)——决定 FAQ 里那句话怎么写。
3. 「为什么 Gitea 作为答疑平台?」是保留精简版还是整段删除。
4. 截图重拍的时间点(建议在平台定制部署上线后)。
+118
View File
@@ -0,0 +1,118 @@
# =============================================================================
# deploy/.env —— 复制为 .env 后填写。.env 已被 .gitignore 排除, 不要提交。
#
# cp .env.example .env
#
# 已有部署的密钥【不要重新生成】: 从现有 /etc/gitea/app.ini 对应段抄写
# (INTERNAL_TOKEN / LFS_JWT_SECRET / oauth2 JWT_SECRET 变更会使已发出的令牌失效)。
#
# 注意: 值里若含 $ 需要写成 $$(compose 会做变量插值); 含 # 或空格要用引号。
# =============================================================================
# -----------------------------------------------------------------------------
# 路径
# -----------------------------------------------------------------------------
# Gitea 数据根目录(容器内挂到 /data), 结构为 gitea/(配置与日志) 与 git/(仓库)
GITEA_DATA_DIR=/srv/gitea
# PostgreSQL 数据目录(容器内挂到 /var/lib/postgresql)
# postgres:18 的布局: 实际数据在 <此目录>/18/docker,
# 所以这里给父目录即可(不要再按老写法挂 /var/lib/postgresql/data)
POSTGRES_DATA_DIR=/srv/pgdata
# -----------------------------------------------------------------------------
# 定制覆盖层(Gitea 客制化: 首页 / 中文术语 / 去 Gitea 化)
# 官方镜像里 GITEA_CUSTOM=/data/gitea, 因此定制内容是挂到
# /data/gitea/{templates,public,options} —— 不是 /data/gitea/custom!
# 这是仓库里的 customization/custom 目录, 相对路径按 deploy/ 解析。
# 生效前先确保产物已生成: python3 customization/build.py
# -----------------------------------------------------------------------------
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
# -----------------------------------------------------------------------------
# 版本(锁定, 便于回滚)
# -----------------------------------------------------------------------------
GITEA_VERSION=1.27.3
POSTGRES_VERSION=18.6
# -----------------------------------------------------------------------------
# 对外地址(必须与现有 Apache 反代一致, 否则链接/克隆地址会错)
# 现有: ROOT_URL = https://cpp.tongji.sh/QA
# Apache: ProxyPass /QA http://localhost:2080
# -----------------------------------------------------------------------------
GITEA_DOMAIN=10.80.42.185
GITEA_ROOT_URL=https://cpp.tongji.sh/QA
GITEA_NO_REPLY_ADDRESS=noreply.10.80.42.185
# 容器发布的回环端口, 必须等于 Apache ProxyPass 的目标端口
GITEA_HTTP_PORT=2080
# 离线模式(沿用现有 app.ini 的 OFFLINE_MODE=true)
GITEA_OFFLINE_MODE=true
# -----------------------------------------------------------------------------
# 容器内 git 用户 uid/gid —— 必须与 GITEA_DATA_DIR 的属主一致
# 现有宿主: /var/lib/gitea 属主 git:git = 982:982
# -----------------------------------------------------------------------------
GITEA_UID=982
GITEA_GID=982
# -----------------------------------------------------------------------------
# 站点名
# ★ 走【裸变量 APP_NAME】(compose 映射为 APP_NAME, 不是 GITEA__*):
# 镜像 /etc/s6/gitea/setup 用 envsubst 渲染模板, 模板第一行是
# `APP_NAME = $APP_NAME`。GITEA__DEFAULT__APP_NAME 不生效(原因见 README)。
# 从现有 app.ini 的【顶层】(无段名)抄写真实值; 全新部署才自行取名。
# -----------------------------------------------------------------------------
GITEA_APP_NAME=Gitea
# -----------------------------------------------------------------------------
# Webhook 出站白名单(逗号分隔; loopback 是内置网络名)
# loopback 为内置项; 其余按实际通知服务填写。
# 从现有 app.ini 的【[security] 段】抄写真实值。
# 段位: 1.27 的规范位置就是 [security]; [webhook] 是 v28.0.0 将移除的
# deprecated fallback(modules/setting/webhook.go)。
# -----------------------------------------------------------------------------
GITEA_ALLOWED_HOST_LIST=loopback,example.com
# -----------------------------------------------------------------------------
# 密钥 —— 【必须沿用现有值】
# INTERNAL_TOKEN / LFS_JWT_SECRET / oauth2 JWT_SECRET 变更会使已发出的令牌失效。
# 从现有 /etc/gitea/app.ini 抄写; 只有全新部署才用 generate secret 生成。
#
# GITEA_SECRET_KEY 特别说明:
# 现有 /etc/gitea/app.ini **没有** SECRET_KEY, 实例一直在用 Gitea 内置默认值。
# 默认留空 = 容器同样使用内置默认值, SSO 与已加密数据行为不变。
# 如需轮换(安全加固), 填一个新的随机值, 但必须在切换后到管理后台
# 重新填写 OIDC(OAuth2)登录源的 Client Secret, 并验证登录。详见 README。
# 生成新值:
# docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret SECRET_KEY
# -----------------------------------------------------------------------------
GITEA_SECRET_KEY=
GITEA_INTERNAL_TOKEN=
GITEA_LFS_JWT_SECRET=
GITEA_OAUTH2_JWT_SECRET=
# -----------------------------------------------------------------------------
# PostgreSQL(容器内部)
# 现有集群: db=giteadb, user=gitea, collate=zh_CN.UTF-8
# -----------------------------------------------------------------------------
POSTGRES_DB=giteadb
POSTGRES_USER=gitea
POSTGRES_PASSWORD=
# -----------------------------------------------------------------------------
# 时区
# -----------------------------------------------------------------------------
TZ=Asia/Shanghai
+1007
View File
File diff suppressed because it is too large Load Diff
+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 分支保护
```
+251
View File
@@ -0,0 +1,251 @@
# =============================================================================
# TJHLP Gitea + PostgreSQL 部署(docker compose v2)
#
# 目标环境: Rocky Linux 8.10 / aarch64
#
# 设计要点:
# * 版本全部锁定(GITEA_VERSION / POSTGRES_VERSION), 可复现、可回滚
# * Gitea 只发布到 127.0.0.1, 由宿主机 Apache 继续反代 /QA -> 127.0.0.1:2080
# (不放 0.0.0.0, 避免绕过反代与 TLS 直连 2080)
# * PostgreSQL 只在内部网络暴露, 不发布到宿主机
# * 所有 app.ini 配置通过 GITEA__section__KEY 环境变量注入(官方镜像支持),
# 不把宿主绝对路径写进配置文件
# * 数据用 bind mount, 便于备份/检查/回滚(见 deploy/README.md)
#
# 用法:
# cp .env.example .env # 填写密钥与路径
# docker compose up -d --build
# docker compose ps
# =============================================================================
name: gitea
services:
db:
# 官方镜像只生成 en_US.UTF-8, 而现有集群是 zh_CN.UTF-8,
# 因此需要一个只加 locale 的派生镜像, 保证迁移后排序语义一致。
build:
context: ./db
args:
POSTGRES_VERSION: ${POSTGRES_VERSION:-18.6}
image: local/gitea-postgres:${POSTGRES_VERSION:-18.6}-zh_CN
container_name: gitea-db
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is required}
POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is required}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
# 与现有集群保持一致: UTF8 + zh_CN.UTF-8 (见 deploy/README.md 的核对结果)
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=zh_CN.UTF-8"
TZ: ${TZ:-Asia/Shanghai}
volumes:
# ★ postgres:18 起数据目录布局变了(见官方 Dockerfile):
# ENV PGDATA /var/lib/postgresql/18/docker
# VOLUME /var/lib/postgresql ← 不再是 .../data
# 所以必须挂到父目录 /var/lib/postgresql。若仍挂 /var/lib/postgresql/data,
# 入口脚本会通过 mountpoint / /proc/self/mountinfo 检测到"未使用的挂载点"
# 并直接 exit 1(docker_error_old_databases)。
# 宿主机上实际数据落在 ${POSTGRES_DATA_DIR}/18/docker
- ${POSTGRES_DATA_DIR:?POSTGRES_DATA_DIR is required}:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 10s
timeout: 5s
retries: 12
start_period: 60s
networks:
- gitea-internal
gitea:
image: docker.gitea.com/gitea:${GITEA_VERSION:?GITEA_VERSION is required}
container_name: gitea
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
# 与宿主机 git 用户 (uid/gid 982) 对齐, 保证 bind mount 权限正确
USER_UID: ${GITEA_UID:-982}
USER_GID: ${GITEA_GID:-982}
TZ: ${TZ:-Asia/Shanghai}
# --- 站点名 ---------------------------------------------------------
# ★ 必须用【裸变量 APP_NAME】, 不能用 GITEA__DEFAULT__APP_NAME:
# 镜像的 /etc/s6/gitea/setup 用 envsubst 渲染 /etc/templates/app.ini,
# 模板第一行就是 `APP_NAME = $APP_NAME` —— 裸变量才是它的来源。
# 而 GITEA__DEFAULT__APP_NAME 到不了顶层 APP_NAME:
# modules/setting/config_env.go 会把段名小写化(strings.ToLower),
# 而 ini 库(gopkg.in/ini.v1)默认段名常量是 "DEFAULT"(大写, 默认区分大小写),
# 于是只会多出一个没用的 [default] 段。
# 注意: 模板只在 app.ini 不存在时渲染; 已有 app.ini 时改这个变量
# 需要删掉 app.ini 让容器重新生成(见 README 5.3)。
APP_NAME: ${GITEA_APP_NAME:?GITEA_APP_NAME is required}
# --- 去 Gitea 化: 站点元信息与页脚 ----------------------------------
# 不填这些时, meta description 会保留 Gitea 自带的
# "a painless self-hosted Git service", 页脚会显示 Powered by Gitea。
# ★ 段名里的点必须编码成 _0X2E_ (config_env.go 的 GITEA__<段>__<键> 规则),
# 即 app.ini 的 [ui.meta] 段要写成 GITEA__ui_0X2E_meta__XXX。
GITEA__ui_0X2E_meta__AUTHOR: ${GITEA_META_AUTHOR:-同济大学高级语言程序设计课程}
GITEA__ui_0X2E_meta__DESCRIPTION: ${GITEA_META_DESCRIPTION:-同济大学高级语言程序设计课程答疑平台}
GITEA__ui_0X2E_meta__KEYWORDS: ${GITEA_META_KEYWORDS:-同济大学,高级语言程序设计,答疑,Issue}
GITEA__other__SHOW_FOOTER_POWERED_BY: "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__HOST: db:5432
GITEA__database__NAME: ${POSTGRES_DB:?POSTGRES_DB is required}
GITEA__database__USER: ${POSTGRES_USER:?POSTGRES_USER is required}
GITEA__database__PASSWD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
GITEA__database__SSL_MODE: disable
GITEA__database__LOG_SQL: "false"
# --- 服务地址(保留 /QA 子路径, 与现有 Apache 反代一致) ---------------
GITEA__server__PROTOCOL: http
GITEA__server__DOMAIN: ${GITEA_DOMAIN:?GITEA_DOMAIN is required}
GITEA__server__ROOT_URL: ${GITEA_ROOT_URL:?GITEA_ROOT_URL is required}
GITEA__server__HTTP_ADDR: 0.0.0.0
GITEA__server__HTTP_PORT: "3000"
GITEA__server__APP_DATA_PATH: /data/gitea
# 关闭 SSH: 界面只提供 HTTP 克隆地址(加公钥时会提示"仅用于提交签名验证")。
# 注意镜像自带 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__LFS_START_SERVER: "true"
GITEA__server__OFFLINE_MODE: ${GITEA_OFFLINE_MODE:-true}
# --- 路径(全部在 /data 内, 不依赖宿主路径) ---------------------------
GITEA__repository__ROOT: /data/git/repositories
GITEA__lfs__PATH: /data/git/lfs
GITEA__indexer__ISSUE_INDEXER_PATH: /data/gitea/indexers/issues.bleve
GITEA__session__PROVIDER: file
GITEA__session__PROVIDER_CONFIG: /data/gitea/sessions
# 容器里日志直接进 stdout, 用 docker compose logs / journald 查看
GITEA__log__MODE: console
GITEA__log__LEVEL: info
# --- 密钥(必须沿用现有值, 否则加密数据/令牌失效) --------------------
GITEA__security__INSTALL_LOCK: "true"
# 现有 /etc/gitea/app.ini 未设置 SECRET_KEY, 实例实际使用 Gitea 内置默认值。
# 留空即保持同一行为(SSO/加密数据不受影响); 旋转换 key 见 deploy/README.md。
GITEA__security__SECRET_KEY: ${GITEA_SECRET_KEY:-}
GITEA__security__INTERNAL_TOKEN: ${GITEA_INTERNAL_TOKEN:?preserve the existing INTERNAL_TOKEN}
GITEA__security__PASSWORD_HASH_ALGO: pbkdf2
GITEA__server__LFS_JWT_SECRET: ${GITEA_LFS_JWT_SECRET:?preserve the existing LFS_JWT_SECRET}
GITEA__oauth2__JWT_SECRET: ${GITEA_OAUTH2_JWT_SECRET:?preserve the existing JWT_SECRET}
# --- 注册与登录(与现有 app.ini 一致: 仅允许外部 OIDC 注册) ----------
GITEA__service__DISABLE_REGISTRATION: "false"
GITEA__service__ALLOW_ONLY_EXTERNAL_REGISTRATION: "true"
GITEA__service__REGISTER_EMAIL_CONFIRM: "false"
GITEA__service__ENABLE_NOTIFY_MAIL: "false"
GITEA__service__ENABLE_CAPTCHA: "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_ALLOW_CREATE_ORGANIZATION: "true"
GITEA__service__DEFAULT_ENABLE_TIMETRACKING: "true"
GITEA__service__NO_REPLY_ADDRESS: ${GITEA_NO_REPLY_ADDRESS:?GITEA_NO_REPLY_ADDRESS is required}
GITEA__mailer__ENABLED: "false"
# --- OIDC / OAuth2 --------------------------------------------------
GITEA__openid__ENABLE_OPENID_SIGNIN: "false"
GITEA__openid__ENABLE_OPENID_SIGNUP: "true"
GITEA__oauth2_client__OPENID_CONNECT_SCOPES: profile email
GITEA__oauth2_client__ENABLE_AUTO_REGISTRATION: "true"
GITEA__oauth2_client__USERNAME: userid
GITEA__oauth2_client__ACCOUNT_LINKING: auto
# [oauth2] ENABLED 默认即为 true, 现有 app.ini 未显式设置;
# 这里显式声明, 避免上游改默认值时行为漂移
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__EXTERNAL_USER_DISABLE_FEATURES: deletion,manage_credentials,change_username,change_full_name
# --- 其它(沿用现有 app.ini) ----------------------------------------
GITEA__cron.update_checker__ENABLED: "true"
GITEA__repository.pull-request__DEFAULT_MERGE_STYLE: merge
GITEA__repository.signing__DEFAULT_TRUST_MODEL: committer
# --- Webhook 出站白名单 ---------------------------------------------
# ★ 该键在 1.27 的规范位置是 [security], 不是 [webhook]。
# 证据: modules/setting/webhook.go (v1.27.3)
# deprecatedSetting(rootCfg, "webhook", "ALLOWED_HOST_LIST",
# "security", "ALLOWED_HOST_LIST", "v28.0.0")
# Webhook.AllowedHostList = sec.Key("ALLOWED_HOST_LIST").MustString(Security.AllowedHostList)
# 即 [webhook] 是 v28.0.0 将移除的 fallback。而且读取时 [webhook] 的值
# 【优先于】[security], 所以千万不要两处都写。
GITEA__security__ALLOWED_HOST_LIST: ${GITEA_ALLOWED_HOST_LIST:?GITEA_ALLOWED_HOST_LIST is required}
# SKIP_TLS_VERIFY 确实属于 [webhook](webhook.go 里就是读 [webhook] 段)
GITEA__webhook__SKIP_TLS_VERIFY: "true"
volumes:
- ${GITEA_DATA_DIR:?GITEA_DATA_DIR is required}:/data
# --- 定制覆盖层(Gitea 客制化, 见 customization/README.md) ------------
# ★ 官方镜像里 GITEA_CUSTOM=/data/gitea, 所以定制文件对应
# /data/gitea/{templates,public,options},
# 不是 /data/gitea/custom(那是源码/二进制安装 WorkPath/custom 的写法,
# 在容器里挂了不会生效)。
# 分开挂三个子目录而不是整目录: 只读覆盖定制内容, 又不遮住同级的
# conf/、log/、indexers/ 等容器自己管理的目录。
# entrypoint 只在 /data/gitea 属主不是 git 时才 chown -R, 现有
# ${GITEA_DATA_DIR}/gitea 属主已是 git, 不会去碰只读挂载。
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/templates:/data/gitea/templates:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/public:/data/gitea/public:ro
- ${GITEA_CUSTOM_DIR:?GITEA_CUSTOM_DIR is required}/options:/data/gitea/options:ro
- /etc/localtime:/etc/localtime:ro
ports:
# 只绑定回环: Apache 反代 /QA -> 127.0.0.1:2080, 不对外暴露
- "127.0.0.1:${GITEA_HTTP_PORT:-2080}:3000"
# 上游 Dockerfile 里有 "HEALTH-CHECK-ENDPOINT: don't use HEALTHCHECK" 的提示,
# 这里显式提供一个: 镜像内自带 curl, /api/healthz 是官方健康端点。
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
interval: 15s
timeout: 5s
retries: 10
start_period: 90s
networks:
- gitea-internal
networks:
gitea-internal:
driver: bridge
-28
View File
@@ -1,28 +0,0 @@
# Copy this file to .env before running docker compose.
# Image versions
GITEA_IMAGE=gitea/gitea:1.26.1
POSTGRES_IMAGE=postgres:18
# Container runtime user
PUID=1000
PGID=1000
# Published ports on the Docker host
GITEA_HTTP_PORT=3000
# Public URL used by Gitea
# For local access you can keep localhost.
GITEA_DOMAIN=localhost
GITEA_ROOT_URL=http://localhost:3000/
# PostgreSQL settings
POSTGRES_DB=gitea
POSTGRES_USER=gitea
POSTGRES_PASSWORD=change_this_db_password
POSTGRES_SSL_MODE=disable
# First admin account used by init-admin.sh
GITEA_ADMIN_USERNAME=admin
GITEA_ADMIN_PASSWORD=ChangeMe!2026
GITEA_ADMIN_EMAIL=[email protected]
-140
View File
@@ -1,140 +0,0 @@
# Docker Compose 部署
- 目标: 单机容器部署 `Gitea + PostgreSQL`
- 不包含: Nginx、TLS 证书、外部对象存储、多节点编排
- 上层使用方式不变: 服务启动后仍然使用 `scripts/` 里的 `tjhlp` CLI 初始化课程组织、仓库、标签和 Webhook
## 文件说明
- `docker-compose.yml`: 启动 Gitea 与 PostgreSQL
- `.env.example`: 本地变量模板, 复制为 `.env` 后修改
- `init-admin.sh`: 读取 `.env` 中的管理员参数并初始化首个管理员账号
## 前置要求
- 已安装 Docker Engine
- 已安装 Docker Compose Plugin, 能执行 `docker compose`
- 目标机器开放 Gitea HTTP 访问端口
## 快速开始
```bash
cd deploy/compose
sudo cp .env.example .env
```
编辑 `.env`, 至少确认这些变量:
- `GITEA_IMAGE` / `POSTGRES_IMAGE`: 要使用的镜像版本
- `GITEA_ROOT_URL`: Gitea 对外访问地址, 必须与实际访问 URL 一致
- `GITEA_DOMAIN`: 对外访问域名或主机名
- `GITEA_HTTP_PORT`: 宿主机暴露的 Gitea 端口
- `POSTGRES_PASSWORD`: PostgreSQL 密码
- `PUID` / `PGID`: 容器内 Gitea 运行用户的 UID/GID, 默认 1000
- `GITEA_ADMIN_USERNAME`
- `GITEA_ADMIN_PASSWORD`
- `GITEA_ADMIN_EMAIL`
启动服务:
```bash
sudo docker compose up -d
sudo docker compose logs -f gitea
```
首次启动后, 运行管理员初始化脚本:
```bash
sudo sh ./init-admin.sh
```
脚本会:
- 从 `.env` 读取 `GITEA_ADMIN_USERNAME`、`GITEA_ADMIN_PASSWORD`、`GITEA_ADMIN_EMAIL`
- 等待 Gitea API 就绪
- 首次运行时创建管理员
- 再次运行时若管理员已存在则直接跳过
创建完成后, 访问 `GITEA_ROOT_URL`, 用 `.env` 中配置的管理员账号登录。
(不推荐Windows)如果你在 Windows 上使用 Docker Desktop, 建议通过 Git Bash 或 WSL 执行 `init-admin.sh`。
## 课程平台初始化
1. 登录 Gitea
2. 在“设置 -> 应用”中创建 API Token
3. 进入仓库 `scripts/` 目录
4. 配置 `.secrets.toml`
5. 执行:
```bash
uv sync
uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f
```
如果是 Docker Compose 部署, 记得把 `scripts/settings.toml` 或环境变量中的 Gitea URL 指向 `GITEA_ROOT_URL`。
例如:
```bash
export TJHLP_GITEA_URL=http://localhost:3000
```
PowerShell:
```powershell
$env:TJHLP_GITEA_URL = "http://localhost:3000"
```
## 常用命令
启动:
```bash
sudo docker compose up -d
```
停止:
```bash
sudo docker compose down
```
查看日志:
```bash
sudo docker compose logs -f gitea
sudo docker compose logs -f postgres
```
升级镜像:
```bash
sudo docker compose pull
sudo docker compose up -d
```
## 数据持久化
本方案使用 Docker 命名卷:
- `gitea_data`: Gitea 仓库、附件、LFS、配置等数据
- `postgres_data`: PostgreSQL 数据目录
删除容器不会删除卷, 但执行带 `--volumes` 的 `docker compose down` 会清空数据。
## 与 Ansible 方案的关系
- `ansible/` 仍然是现有的主机直装方案
- `deploy/compose/` 是新增的单机容器方案
- 两者部署完成后, 上层 `scripts/` 的初始化和日常管理方式一致
## 注意事项
- `.env` 放环境差异和敏感参数, `docker-compose.yml` 保留项目默认策略配置
- 该方案默认只暴露 HTTP, 若要对外提供 HTTPS, 请在外部使用 Nginx/Caddy 等反向代理
- `GITEA_ROOT_URL` 配错时, Web 界面跳转、Webhook 和仓库链接通常会异常
- 如果宿主机已经占用 `3000`, 请调整 `.env` 中的端口映射
- PostgreSQL 默认不对宿主机暴露端口, 以减少额外暴露面
-49
View File
@@ -1,49 +0,0 @@
services:
postgres:
image: ${POSTGRES_IMAGE}
container_name: tjhlp-postgres
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql
gitea:
image: ${GITEA_IMAGE}
container_name: tjhlp-gitea
restart: unless-stopped
depends_on:
- postgres
environment:
USER_UID: ${PUID}
USER_GID: ${PGID}
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: postgres:5432
GITEA__database__NAME: ${POSTGRES_DB}
GITEA__database__USER: ${POSTGRES_USER}
GITEA__database__PASSWD: ${POSTGRES_PASSWORD}
GITEA__database__SSL_MODE: ${POSTGRES_SSL_MODE}
GITEA__server__DOMAIN: ${GITEA_DOMAIN}
GITEA__server__HTTP_PORT: ${GITEA_HTTP_PORT}
GITEA__server__ROOT_URL: ${GITEA_ROOT_URL}
GITEA__server__LFS_START_SERVER: "true"
GITEA__repository__DEFAULT_BRANCH: main
GITEA__repository__DEFAULT_REPO_UNITS: repo.code,repo.issues
GITEA__security__INSTALL_LOCK: "true"
GITEA__service__DISABLE_REGISTRATION: "true"
GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
GITEA__mailer__ENABLED: "false"
GITEA__webhook__ALLOWED_HOST_LIST: "*"
GITEA__webhook__SKIP_TLS_VERIFY: "false"
GITEA__api__ENABLE_SWAGGER: "true"
GITEA__api__MAX_RESPONSE_ITEMS: "100"
ports:
- "${GITEA_HTTP_PORT}:${GITEA_HTTP_PORT}"
volumes:
- gitea_data:/data
volumes:
postgres_data:
gitea_data:
-101
View File
@@ -1,101 +0,0 @@
#!/usr/bin/env sh
set -eu
SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
ENV_FILE="$SCRIPT_DIR/.env"
COMPOSE_FILE="$SCRIPT_DIR/docker-compose.yml"
log() {
printf '%s\n' "$*"
}
fail() {
printf 'Error: %s\n' "$*" >&2
exit 1
}
require_command() {
command -v "$1" >/dev/null 2>&1 || fail "missing required command: $1"
}
require_command docker
[ -f "$COMPOSE_FILE" ] || fail "docker-compose.yml not found in $SCRIPT_DIR"
[ -f "$ENV_FILE" ] || fail ".env not found in $SCRIPT_DIR; copy .env.example to .env first"
set -a
# shellcheck disable=SC1090
. "$ENV_FILE"
set +a
for var_name in GITEA_ADMIN_USERNAME GITEA_ADMIN_PASSWORD GITEA_ADMIN_EMAIL GITEA_ROOT_URL GITEA_HTTP_PORT PUID PGID; do
# 固定列表,非用户输入,无注入风险
eval "var_value=\${$var_name:-}"
[ -n "$var_value" ] || fail "required variable $var_name is missing or empty in .env"
done
dc() {
docker compose --file "$COMPOSE_FILE" --env-file "$ENV_FILE" "$@"
}
check_gitea_ready() {
dc exec -T gitea sh -c "
if command -v wget >/dev/null 2>&1; then
wget -q -O - 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
elif command -v curl >/dev/null 2>&1; then
curl -fsS 'http://127.0.0.1:${GITEA_HTTP_PORT}/api/v1/version' >/dev/null 2>&1
else
exit 1
fi
"
}
dc version >/dev/null 2>&1 || fail "docker compose is not available"
gitea_state=$(dc ps -q gitea 2>/dev/null || true)
[ -n "$gitea_state" ] || fail "gitea service is not created; run 'docker compose up -d' first"
db_state=$(dc ps -q postgres 2>/dev/null || true)
[ -n "$db_state" ] || fail "postgres service is not created; run 'docker compose up -d' first"
log "Waiting for Gitea to become ready at ${GITEA_ROOT_URL%/}/api/v1/version ..."
attempt=0
max_attempts=30
ready=0
# 最长约 60 秒,每 2 秒检查一次
while [ "$attempt" -lt "$max_attempts" ]; do
attempt=$((attempt + 1))
if check_gitea_ready; then
ready=1
break
fi
sleep 2
done
[ "$ready" -eq 1 ] || fail "Gitea did not become ready after $((max_attempts * 2)) seconds"
log "Creating admin user '${GITEA_ADMIN_USERNAME}' if needed ..."
create_output=$(
dc exec -T --user "${PUID}:${PGID}" gitea gitea admin user create \
--admin \
--username "$GITEA_ADMIN_USERNAME" \
--password "$GITEA_ADMIN_PASSWORD" \
--email "$GITEA_ADMIN_EMAIL" 2>&1
) || {
case "$create_output" in
*"already exists"*)
log "Admin user '${GITEA_ADMIN_USERNAME}' already exists; skipping."
exit 0
;;
*)
printf '%s\n' "$create_output" >&2
fail "failed to create admin user"
;;
esac
}
log "Admin user '${GITEA_ADMIN_USERNAME}' created successfully."
+21
View File
@@ -0,0 +1,21 @@
# =============================================================================
# PostgreSQL 派生镜像: 补上 zh_CN.UTF-8 locale
#
# 为什么需要:
# 官方 postgres 镜像在构建时只生成了 en_US.UTF-8
# (见 docker-library/postgres 的 Dockerfile: `echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen`)。
# 而 TJHLP 现有集群的 collation 是 zh_CN.UTF-8:
# giteadb | enc=UTF8 | collate=zh_CN.UTF-8 | ctype=zh_CN.UTF-8
# 若目标集群用 C.UTF-8 / en_US.UTF-8, 恢复后中文文本的排序与索引语义会变,
# 所以这里生成同名 locale, 用 --locale=zh_CN.UTF-8 初始化。
#
# 除了 locale, 不改动官方镜像的任何行为。
# =============================================================================
ARG POSTGRES_VERSION=18.6
FROM docker.io/library/postgres:${POSTGRES_VERSION}
RUN set -eux; \
sed -i 's/^# *zh_CN\.UTF-8 UTF-8/zh_CN.UTF-8 UTF-8/' /etc/locale.gen; \
locale-gen zh_CN.UTF-8; \
locale -a | grep -i 'zh_CN.utf8'
+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
+88
View File
@@ -0,0 +1,88 @@
#!/usr/bin/env bash
# =============================================================================
# 备份正在运行的 Docker 栈 (PostgreSQL + Gitea 数据)
#
# ./backup.sh # 在线备份(不中断服务)
# ./backup.sh --quiesce # 先停 gitea 容器再备份, 得到一致快照
#
# 产物: deploy/backups/<时间戳>/
# postgres-<db>.dump pg_dump 自定义格式
# gitea-data.tar.gz GITEA_DATA_DIR 全量打包
# MANIFEST.txt 版本/大小/时间
# SHA256SUMS 校验和
# =============================================================================
set -euo pipefail
DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd)
cd "$DEPLOY_DIR"
QUIESCE=0
case "${1:-}" in
--quiesce) QUIESCE=1 ;;
-h|--help) sed -n '2,14p' "$0"; exit 0 ;;
"") ;;
*) echo "未知参数: $1" >&2; exit 2 ;;
esac
[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; }
# 逐行读取 .env, 不做 shell 展开($$ 还原为 $)
while IFS= read -r line || [[ -n "$line" ]]; do
[[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
key=${line%%=*}; val=${line#*=}
key=${key//[[:space:]]/}
[[ "$val" == \"*\" || "$val" == \'*\' ]] && val=${val:1:-1}
val=${val//\$\$/\$}
export "${key}=${val}"
done < .env
: "${POSTGRES_DB:?}"; : "${POSTGRES_USER:?}"; : "${GITEA_DATA_DIR:?}"
if ! docker compose ps --status running --format '{{.Service}}' 2>/dev/null | grep -q '^db$'; then
echo "错误: db 容器未运行, 先 docker compose up -d" >&2
exit 1
fi
STAMP=$(date +%Y%m%d-%H%M%S)
OUT="${BACKUP_DIR:-$DEPLOY_DIR/backups}/$STAMP"
mkdir -p "$OUT"
echo "==> 备份目录: $OUT"
if [[ ${QUIESCE} -eq 1 ]]; then
echo "==> 暂停 gitea 容器以保证数据一致"
docker compose stop gitea
fi
echo "==> pg_dump ${POSTGRES_DB}"
docker compose exec -T db pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc \
> "$OUT/postgres-${POSTGRES_DB}.dump"
echo "==> 打包 Gitea 数据目录 ${GITEA_DATA_DIR}"
tar -C "$(dirname "$GITEA_DATA_DIR")" -czf "$OUT/gitea-data.tar.gz" "$(basename "$GITEA_DATA_DIR")"
if [[ ${QUIESCE} -eq 1 ]]; then
echo "==> 恢复 gitea 容器"
docker compose start gitea
fi
{
echo "created_at: $(date -Is)"
echo "hostname: $(hostname)"
echo "gitea_image: $(docker compose config --format json 2>/dev/null | grep -o '"image"[^,]*' | head -1 || true)"
echo "postgres_db: ${POSTGRES_DB}"
echo "gitea_data_dir: ${GITEA_DATA_DIR}"
echo "quiesced: ${QUIESCE}"
echo
du -h "$OUT"/* 2>/dev/null || true
} > "$OUT/MANIFEST.txt"
( cd "$OUT" && sha256sum ./* > SHA256SUMS )
echo "==> 完成"
cat "$OUT/MANIFEST.txt"
echo
echo "恢复数据库:"
echo " docker compose exec -T db pg_restore -U ${POSTGRES_USER} -d ${POSTGRES_DB} --clean --if-exists < $OUT/postgres-${POSTGRES_DB}.dump"
echo "恢复数据目录:"
echo " docker compose stop gitea && tar -C $(dirname "$GITEA_DATA_DIR") -xzf $OUT/gitea-data.tar.gz && docker compose start gitea"
+209
View File
@@ -0,0 +1,209 @@
#!/usr/bin/env bash
# =============================================================================
# 从 deploy/backups/<时间戳>/ 恢复 Gitea 数据与 PostgreSQL
#
# ./scripts/restore.sh --list # 列出可用备份 + 校验状态
# ./scripts/restore.sh <时间戳> # dry-run: 只打印恢复计划
# sudo ./scripts/restore.sh <时间戳> --apply # 真正执行
#
# 选项(可与 --apply 组合):
# --db-only 只恢复数据库
# --data-only 只恢复数据目录
# --no-safety-backup 跳过"恢复前先备份当前状态"(不建议)
#
# 安全设计:
# * 默认 dry-run, 只有 --apply 才动手;
# * 先校验 SHA256SUMS, 任一文件不匹配立即中止;
# * 默认先跑一次 backup.sh --quiesce 保存当前状态, 恢复错了还能退回来;
# * 数据目录不做就地覆盖 —— 先把现有目录改名成 <dir>.pre-restore-<时间戳>,
# 再解包备份, 因此每一步都能手工回退(结尾会打印回退命令)。
# =============================================================================
set -euo pipefail
DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd)
cd "$DEPLOY_DIR"
# ---------- 载入 .env(逐行, 不做 shell 展开; $$ 还原为 $)----------
[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; }
while IFS= read -r line || [[ -n "$line" ]]; do
[[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
key=${line%%=*}; val=${line#*=}
key=${key//[[:space:]]/}
[[ "$val" == \"*\" || "$val" == \'*\' ]] && val=${val:1:-1}
val=${val//\$\$/\$}
export "${key}=${val}"
done < .env
: "${POSTGRES_DB:?}"; : "${POSTGRES_USER:?}"; : "${GITEA_DATA_DIR:?}"
GITEA_UID=${GITEA_UID:-982}
GITEA_GID=${GITEA_GID:-982}
BACKUP_ROOT="${BACKUP_DIR:-$DEPLOY_DIR/backups}"
DUMP_NAME="postgres-${POSTGRES_DB}.dump"
# backup.sh 产出的【容器布局】数据包
DATA_NAME="gitea-data.tar.gz"
# 二进制部署时期的【宿主布局】数据包。顶层同样是 gitea/, 但内部是
# gitea/data/gitea-repositories/... 而容器要的是 gitea/git/repositories/...,
# 直接解到 GITEA_DATA_DIR 只会得到一份 Gitea 认不出的目录, 所以必须拒收。
SOURCE_DATA_NAME="gitea-source-data.tar.gz"
die() { echo "错误: $*" >&2; exit 1; }
step() { echo; echo "==> $*"; }
# ---------- 参数 ----------
MODE_LIST=0; APPLY=0; DO_DB=1; DO_DATA=1; SAFETY=1; STAMP=""
for a in "$@"; do
case "$a" in
--list) MODE_LIST=1 ;;
--apply) APPLY=1 ;;
--db-only) DO_DATA=0 ;;
--data-only) DO_DB=0 ;;
--no-safety-backup) SAFETY=0 ;;
-h|--help) sed -n '2,20p' "$0"; exit 0 ;;
-*) echo "未知参数: $a" >&2; exit 2 ;;
*) STAMP="$a" ;;
esac
done
list_backups() {
[[ -d "$BACKUP_ROOT" ]] || { echo "备份目录不存在: $BACKUP_ROOT"; return 0; }
printf '%-26s %-6s %-7s %-7s %s\n' "时间戳" "校验" "大小" "数据库" "数据目录"
local d name chk size db data
for d in "$BACKUP_ROOT"/*/; do
[[ -d "$d" ]] || continue
name=$(basename "$d")
if [[ -f "$d/SHA256SUMS" ]]; then
if (cd "$d" && sha256sum -c --status SHA256SUMS) 2>/dev/null; then chk="ok"; else chk="损坏"; fi
else
chk="-"
fi
size=$(du -sh "$d" 2>/dev/null | cut -f1)
if [[ -f "$d/$DUMP_NAME" ]]; then db="有"; else db="-"; fi
if [[ -f "$d/$DATA_NAME" ]]; then data="容器布局"
elif [[ -f "$d/$SOURCE_DATA_NAME" ]]; then data="宿主布局, 不可直接恢复"
else data="-"; fi
printf '%-26s %-6s %-7s %-7s %s\n' "$name" "$chk" "$size" "$db" "$data"
done
}
if [[ $MODE_LIST -eq 1 ]]; then
echo "备份目录: $BACKUP_ROOT"
echo
list_backups
exit 0
fi
if [[ -z "$STAMP" ]]; then
echo "已有一份备份清单如下 —— 请把时间戳作为参数传给本脚本。" >&2
echo >&2
list_backups >&2
exit 2
fi
SRC="$BACKUP_ROOT/$STAMP"
[[ -d "$SRC" ]] || die "找不到备份目录: $SRC"
[[ -f "$SRC/SHA256SUMS" ]] || die "缺少 $SRC/SHA256SUMS(无法校验完整性)"
[[ $DO_DB -eq 0 || -f "$SRC/$DUMP_NAME" ]] || die "缺少 $SRC/$DUMP_NAME"
if [[ $DO_DATA -eq 1 && ! -f "$SRC/$DATA_NAME" ]]; then
if [[ -f "$SRC/$SOURCE_DATA_NAME" ]]; then
cat >&2 <<EOF
错误: 该备份里的数据包是 $SOURCE_DATA_NAME —— 二进制部署时期的【宿主布局】备份
(内含 gitea/data/gitea-repositories/...), 与容器要求的 gitea/git/repositories/... 不同,
不能直接解到 $GITEA_DATA_DIR。
只想恢复数据库: 加 --db-only
想回滚到二进制: docker compose down && sudo systemctl start gitea(源数据仍在 /var/lib/gitea)
想要容器布局备份: ./scripts/backup.sh 生成一份新的
EOF
exit 1
fi
die "缺少 $SRC/$DATA_NAME"
fi
step "校验备份完整性"
(cd "$SRC" && sha256sum -c SHA256SUMS)
step "恢复计划"
cat <<EOF
来源 : $SRC
数据库 : $( [[ $DO_DB -eq 1 ]] && echo "$POSTGRES_DB <- $DUMP_NAME (pg_restore --clean --if-exists)" || echo "跳过" )
数据目录 : $( [[ $DO_DATA -eq 1 ]] && echo "$GITEA_DATA_DIR <- $DATA_NAME ($(du -h "$SRC/$DATA_NAME" | cut -f1))" || echo "跳过" )
恢复前备份 : $( [[ $SAFETY -eq 1 ]] && echo "会执行 ./scripts/backup.sh --quiesce" || echo "跳过(--no-safety-backup)" )
数据目录处理 : 现有目录改名 ${GITEA_DATA_DIR}.pre-restore-<时间戳> 后解包(不删除)
EOF
if [[ $APPLY -eq 0 ]]; then
echo
echo "==> 这是 dry-run, 未做任何改动。确认无误后加 --apply 执行。"
exit 0
fi
[[ $EUID -eq 0 ]] || die "--apply 需要 root(读写 $GITEA_DATA_DIR、chown、访问 docker)"
if [[ $SAFETY -eq 1 ]]; then
step "保存当前状态(恢复失败时的退路)"
./scripts/backup.sh --quiesce
fi
step "确保 db 容器在运行"
docker compose up -d db
DB_CID=$(docker compose ps -q db)
[[ -n "$DB_CID" ]] || die "拿不到 db 容器 id"
h=""
for _ in $(seq 1 24); do
h=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$DB_CID" 2>/dev/null || echo "")
[[ "$h" == "healthy" ]] && break
sleep 5
done
[[ "$h" == "healthy" ]] || die "db 容器未变为 healthy(当前: ${h:-未知})"
echo " db: healthy"
step "停止 gitea 容器"
docker compose stop gitea
PRE="${GITEA_DATA_DIR}.pre-restore-$(date +%Y%m%d-%H%M%S)"
if [[ $DO_DATA -eq 1 ]]; then
step "恢复数据目录"
mv "$GITEA_DATA_DIR" "$PRE"
mkdir -p "$(dirname "$GITEA_DATA_DIR")"
tar -C "$(dirname "$GITEA_DATA_DIR")" -xzf "$SRC/$DATA_NAME"
chown -R "${GITEA_UID}:${GITEA_GID}" "$GITEA_DATA_DIR"
echo " 解包完成, 属主已设为 ${GITEA_UID}:${GITEA_GID}"
echo " 旧目录保留在: $PRE"
fi
if [[ $DO_DB -eq 1 ]]; then
step "恢复数据库 $POSTGRES_DB"
if docker compose exec -T db pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
--clean --if-exists --no-owner < "$SRC/$DUMP_NAME"; then
echo " pg_restore 完成"
else
echo " ⚠️ pg_restore 返回非 0 —— 请检查上面的输出。" >&2
echo " 常见无害项: 'does not exist, skipping'。仍以表数量与 verify.sh 为准。" >&2
fi
echo " public schema 表数量: $(docker compose exec -T db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-tAc "select count(*) from information_schema.tables where table_schema='public'")"
fi
step "启动 gitea"
docker compose up -d gitea
G_CID=$(docker compose ps -q gitea)
gh=""
for _ in $(seq 1 24); do
gh=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$G_CID" 2>/dev/null || echo "")
[[ "$gh" == "healthy" ]] && break
sleep 5
done
echo " gitea: ${gh:-未知}"
step "验证"
./scripts/verify.sh || true
echo
echo "==> 恢复结束"
if [[ $DO_DATA -eq 1 ]]; then
echo "若数据目录恢复错了, 回退:"
echo " sudo docker compose stop gitea"
echo " sudo rm -rf '$GITEA_DATA_DIR' && sudo mv '$PRE' '$GITEA_DATA_DIR'"
echo " sudo docker compose start gitea"
fi
+120
View File
@@ -0,0 +1,120 @@
#!/usr/bin/env bash
# =============================================================================
# 部署后验证 —— 只读
#
# ./verify.sh # 容器检查需要 docker 权限
# sudo ./verify.sh # 没加 docker 组时用这个
#
# 检查容器健康、Gitea API、以及经 Apache 反代的对外地址。
# =============================================================================
set -uo pipefail
DEPLOY_DIR=$(cd "$(dirname "$0")/.." && pwd)
cd "$DEPLOY_DIR"
ok() { printf ' [ ok ] %s\n' "$1"; }
bad() { printf ' [FAIL] %s\n' "$1"; }
info() { printf ' [info] %s\n' "$1"; }
warn() { printf ' [warn] %s\n' "$1"; }
# -----------------------------------------------------------------------------
# 本脚本检查的是【本机】端点, 必须绕过 HTTP 代理。
# 若 shell 设了 http_proxy 而 no_proxy 未覆盖 127.0.0.1, 回环请求会被代理接管:
# 本机 mihomo 对 127.0.0.1 直接返回 "502 Bad Gateway", 健康的站点会被误报成故障。
# (实测: 走代理 -> 502; --noproxy '*' -> 200)
# -----------------------------------------------------------------------------
unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY
export no_proxy='*' NO_PROXY='*'
CURL=(curl -sS --noproxy '*' --max-time 10)
[[ -f .env ]] || { echo "错误: 缺少 .env" >&2; exit 1; }
while IFS= read -r line || [[ -n "$line" ]]; do
[[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
key=${line%%=*}; val=${line#*=}
key=${key//[[:space:]]/}
[[ "$val" == \"*\" || "$val" == \'*\' ]] && val=${val:1:-1}
val=${val//\$\$/\$}
export "${key}=${val}"
done < .env
HTTP_PORT=${GITEA_HTTP_PORT:-2080}
ROOT_URL=${GITEA_ROOT_URL:-http://127.0.0.1/}
FAIL=0
echo "=============================================="
echo " 部署验证"
echo "=============================================="
echo
echo "-- 容器状态 --"
DOCKER_OK=0
if docker info >/dev/null 2>&1; then
DOCKER_OK=1
docker compose ps
else
warn "无法访问 docker daemon —— 容器状态与健康检查跳过"
info " 用 sudo 运行可完整检查: sudo $0"
info " (或把用户加入 docker 组; 那等于免密 root, 取舍见 deploy/README.md 第 3 节)"
fi
if [[ ${DOCKER_OK} -eq 1 ]]; then
echo
echo "-- 健康检查 --"
# 刚 --force-recreate / restart 过的容器, 在 start_period(60s)内状态是 "starting",
# 这是正常过渡态而不是故障 —— 最多等 60s, 避免把启动过程误报成 [FAIL]。
# (与下面回环检查是同一类竞态: verify.sh 常常紧接着一次重建被执行。)
for c in gitea-db gitea; do
st=""
for i in $(seq 1 12); do
st=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$c" 2>/dev/null || echo missing)
if [[ "$st" != "starting" && "$st" != "created" ]]; then break; fi
if [[ $i -eq 1 ]]; then echo " (${c} 正在启动, 最多等 60s ...)"; fi
sleep 5
done
if [[ "$st" == "healthy" || "$st" == "running" ]]; then ok "$c: $st"; else bad "$c: $st"; FAIL=1; fi
done
fi
echo
echo "-- 本机回环 API (127.0.0.1:${HTTP_PORT}) --"
# 刚 restart 过的容器有一小段窗口: docker-proxy 已接管端口, 但 gitea 还没开始 listen,
# 此时 docker-proxy 会返回 502。给最多 30s 的重试, 避免把启动竞态误报成故障。
# 注意: 这里不用 curl -f —— 我们要的是状态码本身(502 也是有效信息),
# 加了 -f 会退出非 0, 再配合 "|| echo 000" 就会把 502 和 000 拼成 "502000"。
code=""
for i in $(seq 1 7); do
code=$("${CURL[@]}" -o /dev/null -w '%{http_code}' \
"http://127.0.0.1:${HTTP_PORT}/api/healthz" 2>/dev/null) || code=000
if [[ "$code" == "200" ]]; then break; fi
if [[ $i -eq 1 ]]; then echo " (本机 API 尚未就绪, 最多等 30s ...)"; fi
sleep 5
done
if [[ "$code" == "200" ]]; then ok "/api/healthz -> 200"; else bad "/api/healthz -> $code"; FAIL=1; fi
ver=$("${CURL[@]}" "http://127.0.0.1:${HTTP_PORT}/api/v1/version" 2>/dev/null || true)
if [[ -n "$ver" ]]; then ok "/api/v1/version -> $ver"; else bad "/api/v1/version 无响应"; FAIL=1; fi
echo
echo "-- 经 Apache 反代 (${ROOT_URL}) --"
root=${ROOT_URL%/}
code=$("${CURL[@]}" -o /dev/null -w '%{http_code}' "${root}/api/v1/version" 2>/dev/null) || code=000
if [[ "$code" == "200" ]]; then ok "${root}/api/v1/version -> 200"; else bad "${root}/api/v1/version -> $code (检查 httpd 反代)"; FAIL=1; fi
if [[ ${DOCKER_OK} -eq 1 ]]; then
echo
echo "-- 日志尾部(容器) --"
docker compose logs --tail=15 gitea 2>/dev/null | sed 's/^/ /'
fi
echo
if [[ ${FAIL} -eq 0 ]]; then
if [[ ${DOCKER_OK} -eq 1 ]]; then
echo "==> 全部通过"
else
echo "==> HTTP 检查全部通过 (容器状态未检查: 需要 docker 权限)"
fi
else
echo "==> 存在失败项, 请检查上方 [FAIL]"
exit 1
fi
+28 -3
View File
@@ -17,16 +17,36 @@
issue-templates/ issue-templates/
├── general/ general 仓库使用 ├── general/ general 仓库使用
│ └── .gitea/ISSUE_TEMPLATE/ │ └── .gitea/ISSUE_TEMPLATE/
│ ├── config.yaml 禁止空白 Issue + 外部链接 │ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接
│ ├── course-question.yaml 课程内容 / 知识点答疑 │ ├── course-question.yaml 课程内容 / 知识点答疑
│ ├── homework-help.yaml 编程作业问题 │ ├── homework-help.yaml 编程作业问题
│ └── env-setup.yaml 环境配置问题 │ └── env-setup.yaml 环境配置问题
└── homework/ hwXX 作业仓库使用 └── homework/ hwXX 作业仓库使用
└── .gitea/ISSUE_TEMPLATE/ └── .gitea/ISSUE_TEMPLATE/
├── config.yaml 禁止空白 Issue + 引导到 general ├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接
└── homework-help.yaml 编程作业问题(无作业编号字段) └── homework-help.yaml 编程作业问题(无作业编号字段)
``` ```
## config.yaml 里的链接与占位符
`config.yaml` 的 `contact_links` 是「新建 Issue」页面上的引导入口, 目前指向**课程官网**
(提问指南 / 课程信息), 把答疑平台和官网串起来。提问指南只在官网保留一份
(`https://cpp.tongji.sh/Website/qa/ask/`, 平台内不再有副本); 课程官网地址是硬编码常量
(`https://cpp.tongji.sh/Website/`), 换域名时两个 `config.yaml` 要一起改。
平台自身的链接用占位符, 避免把学期组织名写死:
| 占位符 | 替换为 | 来源 |
|--------|--------|------|
| `{{BASE_URL}}` | 面向同学的平台地址 | `scripts/settings.toml` 的 `gitea.public_url` |
| `{{ORG}}` | 组织名(如 `tjhlp-2025f`) | 推送时的目标仓库 |
| `{{REPO}}` | 仓库名(如 `hw01`) | 推送时的目标仓库 |
> 换学期只要新建组织、重跑 `setup init` / `create-homework`, 模板里的链接会自动跟着走。
> `public_url` 没配时会保留占位符并打印警告, 不会推上一条坏链接。
> 注意 `gitea.url`(CLI 调 API 用, 带内部端口)与 `public_url`(Apache 反代后的对外地址)
> 是两回事, 写进模板的必须是后者。
## 模板说明 ## 模板说明
### general 仓库(3 个模板) ### general 仓库(3 个模板)
@@ -97,10 +117,15 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
## 自定义 ## 自定义
如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送: 如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接),
直接编辑对应的 YAML 文件, 然后重新推送:
```bash ```bash
# 已有仓库原地更新(general 与各 hwNN 都要推一次)
uv run tjhlp repos init-templates tjhlp-2025f/general --type general uv run tjhlp repos init-templates tjhlp-2025f/general --type general
uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
``` ```
推送会覆盖远端同名文件(走 API 的 create-or-update), 不需要重建仓库。
YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。 YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。
@@ -1,8 +1,8 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: 课程主页 - name: 提问前必读 · 提问指南
url: https://example.com url: http://10.80.42.185/Website/qa/ask/
about: 访问课程主页获取有关资源 about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 常见问题汇总 - name: 课程官网
url: https://example.com/faq url: http://10.80.42.185/Website/
about: 提问前请先查阅常见问题汇总 about: 课程信息、作业说明、环境配置要求、常见问题
@@ -1,5 +1,11 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: 一般性问题请到 general 仓库提问 - name: 一般性问题请到 general 仓库提问
url: https://example.com url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose"
about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库 about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库
- name: 提问前必读 · 提问指南
url: https://cpp.tongji.sh/Website/qa/ask/
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 课程官网
url: https://cpp.tongji.sh/Website/
about: 课程信息、作业说明、环境配置要求、常见问题
-1
View File
@@ -9,7 +9,6 @@ build/
*.egg *.egg
# Pytest # Pytest
.pytest_tmp/
.coverage .coverage
# Secrets & credentials # Secrets & credentials
+51 -24
View File
@@ -1,6 +1,6 @@
# Python CLI 管理工具 # Python CLI 管理工具
`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。 `tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。
## 前置要求 ## 前置要求
@@ -28,7 +28,7 @@ uv sync
cp .secrets.toml.example .secrets.toml cp .secrets.toml.example .secrets.toml
``` ```
编辑 `.secrets.toml`, 填入实际值: 编辑 `.secrets.toml`, 填入实际值:
```toml ```toml
[default.gitea] [default.gitea]
@@ -41,7 +41,7 @@ API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选
### 环境变量覆盖 ### 环境变量覆盖
所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖: 所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖:
```bash ```bash
export TJHLP_GITEA_URL=http://192.168.1.100:3000 export TJHLP_GITEA_URL=http://192.168.1.100:3000
@@ -56,7 +56,7 @@ tjhlp
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook │ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态 │ └── status 检查 Gitea 连接状态
├── users ├── users
│ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV) │ ├── create 从 CSV 批量创建账号(随机密码)
│ ├── list 列出所有用户 │ ├── list 列出所有用户
│ └── delete 批量删除用户 │ └── delete 批量删除用户
├── orgs ├── orgs
@@ -77,9 +77,12 @@ tjhlp
├── labels ├── labels
│ ├── sync 同步预定义 Label 到仓库 │ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label │ └── list 列出仓库 Label
└── stats ├── stats
├── summary Issue 统计摘要 │ ├── summary Issue 统计摘要
└── export 导出 Issue 数据到 CSV │ └── export 导出 Issue 数据到 CSV
└── labels
├── sync 同步预定义 Label 到仓库
└── list 列出仓库 Label
``` ```
## 典型工作流 ## 典型工作流
@@ -100,14 +103,29 @@ uv run tjhlp setup init \
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
``` ```
执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。
`cmd` 可直接复制的写法: ## 典型工作流
```cmd ### 学期初始化
```bash
# 1. 检查连接
uv run tjhlp setup status uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
uv run tjhlp setup init \
--org tjhlp-2025f \
--webhook-url http://notify-server:8080/webhook \
--webhook-secret mysecret
# 3. 批量创建用户并分配到团队
uv run tjhlp users create --file members.csv --org tjhlp-2025f uv run tjhlp users create --file members.csv --org tjhlp-2025f
# 4. 发送账号密码邮件
uv run tjhlp notify send-credentials --file credentials_20250901_120000.csv
# 5. (可选)先预览邮件, 不实际发送
uv run tjhlp notify send-credentials --file credentials_*.csv --dry-run
``` ```
### 每次布置作业 ### 每次布置作业
@@ -120,12 +138,6 @@ uv run tjhlp repos create-homework \
--webhook-url http://notify-server:8080/webhook --webhook-url http://notify-server:8080/webhook
``` ```
`cmd` 可直接复制的写法:
```cmd
uv run tjhlp repos create-homework --org tjhlp-2025f --number 3 --desc "作业3: 链表操作" --webhook-url http://notify-server:8080/webhook
```
这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。 这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
### 日常管理 ### 日常管理
@@ -144,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
@@ -162,16 +188,16 @@ id,name,role
``` ```
- `id` - 学号或工号, 同时作为 Gitea 用户名 - `id` - 学号或工号, 同时作为 Gitea 用户名
- `name` - 姓名, 作为 Gitea 的 `full_name` - `name` - 姓名, 作为 Gitea 的 full_name
- `role` - `student` 或 `ta`, 决定分配到哪个团队 - `role` - `student` 或 `ta`, 决定分配到哪个团队
- 邮箱自动生成为 `{id}@tongji.edu.cn` - 邮箱自动生成为 `{id}@tongji.edu.cn`
- 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV - **初始密码与用户名(学号/工号)相同**。
示例文件见 `example/members.csv`。 示例文件见 `example/members.csv`。
## 预定义 Label ## 预定义 Label
通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建: 通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建:
| Label | 颜色 | 用途 | | Label | 颜色 | 用途 |
|-------|------|------| |-------|------|------|
@@ -197,15 +223,15 @@ uv sync --extra dev
### 运行测试 ### 运行测试
```bash ```bash
uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试 uv run pytest tests/ -v # 全部测试
uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试 uv run pytest tests/test_models.py # 只运行模型测试
uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤 uv run pytest tests/ -k "password" # 按名称过滤
``` ```
### 覆盖率报告 ### 覆盖率报告
```bash ```bash
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp uv run pytest tests/ --cov=tjhlp --cov-report=term-missing
``` ```
### 代码检查 ### 代码检查
@@ -259,6 +285,7 @@ scripts/
│ ├── test_models.py 数据模型测试 │ ├── test_models.py 数据模型测试
│ ├── test_config.py 配置校验测试 │ ├── test_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试 │ ├── test_utils.py 工具函数测试
│ ├── test_pure_functions.py 纯函数测试
│ ├── test_client.py API 客户端测试 │ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试 │ └── test_commands.py 命令集成测试
└── src/tjhlp/ └── src/tjhlp/
+4 -1
View File
@@ -1,5 +1,8 @@
[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)。
# 用于 Issue Template 等面向用户的链接; url 只用于 CLI 调 API。
public_url = "https://cpp.tongji.sh/QA"
email_domain = "tongji.edu.cn" email_domain = "tongji.edu.cn"
default_org = "" default_org = ""
+3 -3
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import get_gitea_config from tjhlp.config import get_gitea_config
from tjhlp.utils import parse_repo, push_templates, sync_labels from tjhlp.utils import parse_repo, push_templates, sync_labels, web_base_url
app = typer.Typer(no_args_is_help=True) app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@@ -69,7 +69,7 @@ def create_homework(
# 推送作业 Issue Templates # 推送作业 Issue Templates
console.print("\n推送 Issue Templates...") console.print("\n推送 Issue Templates...")
hw_tpl_dir = _TEMPLATES_DIR / "homework" hw_tpl_dir = _TEMPLATES_DIR / "homework"
n = push_templates(client, org, repo_name, hw_tpl_dir) n = push_templates(client, org, repo_name, hw_tpl_dir, web_base_url(cfg))
console.print(f" 共推送 {n} 个模板文件") console.print(f" 共推送 {n} 个模板文件")
# 同步 Labels # 同步 Labels
@@ -120,7 +120,7 @@ def init_templates(
cfg = get_gitea_config() cfg = get_gitea_config()
with GiteaClient(cfg) as client: with GiteaClient(cfg) as client:
n = push_templates(client, org_name, repo_name, tpl_dir) n = push_templates(client, org_name, repo_name, tpl_dir, web_base_url(cfg))
console.print(f"\n共推送 {n} 个模板文件到 {repo}") console.print(f"\n共推送 {n} 个模板文件到 {repo}")
+2 -2
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import get_gitea_config from tjhlp.config import get_gitea_config
from tjhlp.utils import push_templates, sync_labels from tjhlp.utils import push_templates, sync_labels, web_base_url
app = typer.Typer(no_args_is_help=True) app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@@ -86,7 +86,7 @@ def init(
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]") console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
general_tpl_dir = _TEMPLATES_DIR / "general" general_tpl_dir = _TEMPLATES_DIR / "general"
if general_tpl_dir.exists(): if general_tpl_dir.exists():
n = push_templates(client, org, "general", general_tpl_dir) n = push_templates(client, org, "general", general_tpl_dir, web_base_url(cfg))
console.print(f" 共推送 {n} 个模板文件") console.print(f" 共推送 {n} 个模板文件")
else: else:
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]") console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
+4 -95
View File
@@ -3,8 +3,7 @@
import csv import csv
import secrets import secrets
import string import string
from dataclasses import dataclass from datetime import UTC, datetime
from datetime import datetime
from pathlib import Path from pathlib import Path
import typer import typer
@@ -19,17 +18,6 @@ app = typer.Typer(no_args_is_help=True)
console = Console() console = Console()
@dataclass
class CredentialRecord:
id: str
name: str
role: str
email: str
status: str
password: str
message: str
def _read_members_csv(filepath: Path) -> list[MemberRecord]: def _read_members_csv(filepath: Path) -> list[MemberRecord]:
"""读取 members CSV 文件""" """读取 members CSV 文件"""
records: list[MemberRecord] = [] records: list[MemberRecord] = []
@@ -40,45 +28,13 @@ def _read_members_csv(filepath: Path) -> list[MemberRecord]:
return records return records
def _generate_password(length: int = 12) -> str:
"""
生成随机密码 \\
仅包含字母和数字
"""
alphabet = string.ascii_letters + string.digits
return "".join(secrets.choice(alphabet) for _ in range(length))
def _write_credentials_csv(records: list[CredentialRecord]) -> Path:
output_path = Path(f"credentials_{datetime.now():%Y%m%d_%H%M%S}.csv")
with output_path.open("w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(
f,
fieldnames=["id", "name", "role", "email", "status", "password", "message"],
)
writer.writeheader()
for record in records:
writer.writerow(
{
"id": record.id,
"name": record.name,
"role": record.role,
"email": record.email,
"status": record.status,
"password": record.password,
"message": record.message,
}
)
return output_path
@app.command("create") @app.command("create")
def create_users( def create_users(
file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"),
org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"), org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"),
dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"), dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"),
) -> None: ) -> None:
"""从 CSV 批量创建用户账号(随机初始密码, 自动导出凭据 CSV)""" """从 CSV 批量创建用户账号(初始密码与用户名相同)"""
if not file.exists(): if not file.exists():
console.print(f"[red]文件不存在: {file}[/red]") console.print(f"[red]文件不存在: {file}[/red]")
raise typer.Exit(code=1) raise typer.Exit(code=1)
@@ -103,8 +59,6 @@ def create_users(
return return
stats = {"created": 0, "skipped": 0, "failed": 0} stats = {"created": 0, "skipped": 0, "failed": 0}
# 用于记录创建结果
credential_records: list[CredentialRecord] = []
with GiteaClient(cfg) as client: with GiteaClient(cfg) as client:
# 获取团队 ID(如果指定了组织) # 获取团队 ID(如果指定了组织)
@@ -115,36 +69,23 @@ def create_users(
students_team = client.get_team_by_name(org, "students") students_team = client.get_team_by_name(org, "students")
for member in members: for member in members:
# 检查用户是否已存在,仅校验用户名是否存在 # 检查用户是否已存在
existing = client.get_user(member.username) existing = client.get_user(member.username)
if existing: if existing:
console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在") console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在")
stats["skipped"] += 1 stats["skipped"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="skipped",
password="",
message="user already exists",
)
)
continue continue
try: try:
password = _generate_password()
client.create_user( client.create_user(
username=member.username, username=member.username,
password=password, password=member.username,
email=member.email, email=member.email,
full_name=member.name, full_name=member.name,
must_change_password=True, must_change_password=True,
) )
console.print(f" [green]创建[/green] {member.username}({member.name})") console.print(f" [green]创建[/green] {member.username}({member.name})")
stats["created"] += 1 stats["created"] += 1
message = "created"
# 添加到团队 # 添加到团队
if org: if org:
@@ -154,46 +95,14 @@ def create_users(
client.add_team_member(team.id, member.username) client.add_team_member(team.id, member.username)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]") console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]")
message = f"created; team assignment failed: {e.message}"
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="created",
password=password,
message=message,
)
)
except GiteaClientError as e: except GiteaClientError as e:
console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}") console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}")
stats["failed"] += 1 stats["failed"] += 1
credential_records.append(
CredentialRecord(
id=member.id,
name=member.name,
role=member.role,
email=member.email,
status="failed",
password="",
message=e.message,
)
)
try:
output_path = _write_credentials_csv(credential_records)
except OSError as e:
console.print(f"[red]凭据导出失败: {e}[/red]")
console.print("[yellow]用户创建结果可能已部分生效, 请先检查 Gitea 中的实际状态, 不要直接重试整批导入。[/yellow]")
raise typer.Exit(code=1) from e
console.print( console.print(
f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}"
) )
console.print(f"凭据已导出: {output_path}")
@app.command("list") @app.command("list")
+4
View File
@@ -55,6 +55,10 @@ class GiteaConfig(BaseModel):
token: SecretStr token: SecretStr
email_domain: str = "tongji.edu.cn" email_domain: str = "tongji.edu.cn"
default_org: str = "" default_org: str = ""
# 面向用户的访问地址(Apache 反代后的地址, 如 https://cpp.tongji.sh/QA)。
# url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等
# 给同学看的链接里; 留空时回退到 url。
public_url: str = ""
labels: list[LabelDef] = [] labels: list[LabelDef] = []
+34 -1
View File
@@ -34,11 +34,38 @@ def parse_repo(repo: str) -> tuple[str, str]:
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# Issue Template 推送 # Issue Template 推送
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# 模板占位符: 让 Issue Template 不必硬编码学期组织名/访问地址
# {{BASE_URL}} -> gitea.public_url(面向同学的地址)
# {{ORG}} / {{REPO}} -> 推送目标
TEMPLATE_PLACEHOLDERS = ("{{BASE_URL}}", "{{ORG}}", "{{REPO}}")
def web_base_url(cfg: GiteaConfig) -> str:
"""面向同学的平台访问地址: 优先 gitea.public_url, 否则退回 gitea.url。"""
return (cfg.public_url or str(cfg.url)).rstrip("/")
def render_template_placeholders(text: str, org: str, repo: str, web_base: str = "") -> str:
"""替换 Issue Template 中的占位符, 返回渲染后的文本。"""
base = (web_base or "").rstrip("/")
if base:
text = text.replace("{{BASE_URL}}", base)
text = text.replace("{{ORG}}", org).replace("{{REPO}}", repo)
left = [p for p in TEMPLATE_PLACEHOLDERS if p in text]
if left:
console.print(
f"[yellow]警告: 模板中仍有未替换的占位符 {', '.join(left)}"
f"(检查 settings.toml 的 gitea.public_url)[/yellow]"
)
return text
def push_templates( def push_templates(
client: GiteaClient, client: GiteaClient,
org: str, org: str,
repo: str, repo: str,
template_dir: Path, template_dir: Path,
web_base: str = "",
) -> int: ) -> int:
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。""" """将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
count = 0 count = 0
@@ -51,7 +78,13 @@ def push_templates(
if not filepath.is_file(): if not filepath.is_file():
continue continue
remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}" remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}"
content_b64 = base64.b64encode(filepath.read_bytes()).decode() text = render_template_placeholders(
filepath.read_text(encoding="utf-8"),
org=org,
repo=repo,
web_base=web_base,
)
content_b64 = base64.b64encode(text.encode("utf-8")).decode()
existing = client.get_file_contents(org, repo, remote_path) existing = client.get_file_contents(org, repo, remote_path)
if existing: if existing:
+13 -94
View File
@@ -2,6 +2,7 @@
from __future__ import annotations from __future__ import annotations
import csv
from pathlib import Path from pathlib import Path
from unittest.mock import MagicMock, patch from unittest.mock import MagicMock, patch
@@ -10,7 +11,6 @@ from pydantic import HttpUrl, SecretStr
from typer.testing import CliRunner from typer.testing import CliRunner
from tjhlp.cli import app from tjhlp.cli import app
from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import GiteaConfig, LabelDef from tjhlp.config import GiteaConfig, LabelDef
from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser
@@ -104,16 +104,9 @@ class TestUsersCreateDryRun:
class TestUsersCreate: class TestUsersCreate:
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_creates_users( def test_creates_users(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path):
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient) client = MagicMock()
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None # user doesn't exist client.get_user.return_value = None # user doesn't exist
@@ -123,7 +116,6 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke( result = runner.invoke(
app, app,
@@ -133,44 +125,22 @@ class TestUsersCreate:
"--file", "--file",
str(csv_file), str(csv_file),
], ],
catch_exceptions=False,
) )
assert result.exit_code == 0 assert result.exit_code == 0
assert "创建" in result.output assert "创建" in result.output
assert "凭据已导出:" in result.output client.create_user.assert_called_once_with(
client.create_user.assert_called_once() username="2659999",
call_kwargs = client.create_user.call_args.kwargs password="2659999",
assert call_kwargs["username"] == "2659999" email="[email protected]",
assert call_kwargs["email"] == "[email protected]" full_name="赵一伤",
assert call_kwargs["full_name"] == "赵一伤" must_change_password=True,
assert call_kwargs["must_change_password"] is True )
assert call_kwargs["password"] != "2659999"
assert len(call_kwargs["password"]) >= 12
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "created" in content
assert "2659999" in content
@patch("tjhlp.commands.users.GiteaClient") @patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config") @patch("tjhlp.commands.users.get_gitea_config")
def test_skips_existing_user( def test_skips_existing_user(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path):
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户已存在时,是否正常导出凭据,且凭据中包含已存在的用户名和错误信息
预期:
- 用户已存在时,凭据导出文件中包含已存在的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient) client = MagicMock()
client.__enter__ = MagicMock(return_value=client) client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False) client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists
@@ -178,62 +148,11 @@ class TestUsersCreate:
csv_file = tmp_path / "members.csv" csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke( result = runner.invoke(app, ["users", "create", "--file", str(csv_file)])
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0 assert result.exit_code == 0
assert "跳过" in result.output assert "跳过" in result.output
client.create_user.assert_not_called() client.create_user.assert_not_called()
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "skipped" in content
assert "user already exists" in content
@patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config")
def test_exports_failed_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户创建失败时,凭据是否正常导出
预期:
- 用户创建失败时,凭据导出文件中包含失败的用户名和错误信息
"""
mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient)
client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None
client.create_user.side_effect = GiteaClientError(400, "PasswordIsRequired")
mock_client_cls.return_value = client
csv_file = tmp_path / "members.csv"
csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8")
monkeypatch.chdir(tmp_path)
result = runner.invoke(
app,
["users", "create", "--file", str(csv_file)],
catch_exceptions=False,
)
assert result.exit_code == 0
credential_files = list(tmp_path.glob("credentials_*.csv"))
assert len(credential_files) == 1
content = credential_files[0].read_text(encoding="utf-8-sig")
assert "failed" in content
assert "PasswordIsRequired" in content
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
+50 -2
View File
@@ -1,10 +1,17 @@
"""utils.py 单元测试: parse_repo, compute_issue_stats""" """utils.py 单元测试: parse_repo, compute_issue_stats, render_template_placeholders"""
from __future__ import annotations from __future__ import annotations
import pytest import pytest
from pydantic import SecretStr
from tjhlp.utils import compute_issue_stats, parse_repo from tjhlp.config import GiteaConfig
from tjhlp.utils import (
compute_issue_stats,
parse_repo,
render_template_placeholders,
web_base_url,
)
# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit # typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit
_EXIT_EXCEPTIONS = (SystemExit, Exception) _EXIT_EXCEPTIONS = (SystemExit, Exception)
@@ -103,3 +110,44 @@ class TestComputeIssueStats:
] ]
stats = compute_issue_stats(issues) stats = compute_issue_stats(issues)
assert stats["no_reply"] == 1 assert stats["no_reply"] == 1
class TestRenderTemplatePlaceholders:
def test_replaces_all_placeholders(self):
out = render_template_placeholders(
'url: "{{BASE_URL}}/{{ORG}}/{{REPO}}/issues"',
org="tjhlp-2025f",
repo="hw01",
web_base="https://cpp.tongji.sh/QA/",
)
assert out == 'url: "https://cpp.tongji.sh/QA/tjhlp-2025f/hw01/issues"'
def test_strips_trailing_slash_of_web_base(self):
out = render_template_placeholders(
"{{BASE_URL}}/assets/x.html", "org", "repo", "http://h/QA//"
)
assert out == "http://h/QA/assets/x.html"
def test_leaves_base_url_when_not_configured(self):
# public_url 没配时应保留占位符(由 push_templates 打警告), 而不是生成坏链接
out = render_template_placeholders("{{BASE_URL}}/x", "org", "repo")
assert "{{BASE_URL}}" in out
def test_text_without_placeholders_is_unchanged(self):
text = "blank_issues_enabled: false\n"
assert render_template_placeholders(text, "org", "repo", "http://h") == text
class TestWebBaseUrl:
def _cfg(self, **kw):
base = {"url": "https://cpp.tongji.sh:3000", "token": SecretStr("x")}
return GiteaConfig(**{**base, **kw})
def test_prefers_public_url(self):
assert (
web_base_url(self._cfg(public_url="https://cpp.tongji.sh/QA/"))
== "https://cpp.tongji.sh/QA"
)
def test_falls_back_to_url(self):
assert web_base_url(self._cfg()) == "https://cpp.tongji.sh:3000"