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
*.key
# Ansible
*.retry
# Deployment (docker compose)
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
.idea/
@@ -33,10 +42,3 @@ Thumbs.db
# 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
tjhlp-gitea/
├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL)
├── deploy/ 测试使用的部署方案(如 Docker Compose)
├── deploy/ Docker 部署与运维(Gitea + PostgreSQL)
├── customization/ Gitea 客制化(首页、中文术语、去 Gitea 化)与本地预览
├── issue-templates/ Issue 模板(按仓库类型区分)
└── scripts/ Python CLI 管理工具
```
## 快速开始
### 1. 选择部署方式
### 1. 部署服务器
本项目当前提供两种并行的单机部署方式:
- **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。
需要一台 Rocky Linux 8.10 服务器, 以及 Docker(含 compose 插件)。
```bash
cd ansible
cp inventory/hosts.yml.example inventory/hosts.yml
cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml
cd deploy
cp .env.example .env # 填写地址、密钥、密码
docker compose config --quiet # 校验 compose 与 .env 插值
docker compose up -d --build
sudo ./scripts/verify.sh # 体检
```
编辑 ansible/inventory/hosts.yml 填入服务器地址
编辑 ansible/inventory/group_vars/all.yml 修改域名、密码等
完整的部署步骤(Docker 安装、外网代理、RPM 冲突处理), 以及 **备份 / 恢复 / 升级**
流程, 见 [`deploy/README.md`](deploy/README.md)。
```bash
ansible-playbook playbook.yml
```
部署完成后, Ansible 会自动创建管理员账号并输出访问地址。
### 3. 初始化平台
### 2. 初始化平台
登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后:
@@ -68,7 +55,7 @@ uv run tjhlp setup init --org tjhlp-2025f
这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。
### 4. 导入用户
### 3. 导入用户
准备 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
```
### 5. 创建作业仓库
### 4. 创建作业仓库
```bash
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
cd scripts
uv sync --extra dev
uv run pytest tests/ -v --basetemp .pytest_tmp # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing --basetemp .pytest_tmp # 带覆盖率
uv run pytest tests/ -v # 运行全部测试
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率
```
当前测试套件包含 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
- **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程
### Ansible 静态检查
### 部署配置检查
```bash
cd ansible
ansible-playbook --syntax-check playbook.yml # 语法检查
yamllint -c .yamllint.yml . # YAML 格式
ansible-lint playbook.yml # 最佳实践
cd deploy
docker compose config --quiet # 校验 compose 与 .env 插值
sudo ./scripts/verify.sh # 部署后验证(容器健康 + API + 反代)
./scripts/restore.sh --list # 查看可用备份及校验状态
```
### Issue Templates 验证
@@ -130,17 +117,31 @@ ansible-lint playbook.yml # 最佳实践
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。
## 技术栈
| 组件 | 技术选型 |
| ------ | ---------- |
| Git 平台 | Gitea(二进制 + systemd) |
| 数据库 | PostgreSQL 18 |
| 服务器 | Rocky Linux 8.10 |
| 部署工具 | Ansible / Docker Compose |
| Git 平台 | Gitea(Docker 容器) |
| 数据库 | PostgreSQL 18(Docker 容器) |
| 服务器 | Rocky Linux 8.10 (aarch64) |
| 部署工具 | Docker Compose(见 `deploy/`) |
| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf |
| 包管理 | uv |
| 测试框架 | 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.24.7
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/
├── general/ general 仓库使用
│ └── .gitea/ISSUE_TEMPLATE/
│ ├── config.yaml 禁止空白 Issue + 外部链接
│ ├── config.yaml 禁止空白 Issue + 课程官网/提问规范链接
│ ├── course-question.yaml 课程内容 / 知识点答疑
│ ├── homework-help.yaml 编程作业问题
│ └── env-setup.yaml 环境配置问题
└── homework/ hwXX 作业仓库使用
└── .gitea/ISSUE_TEMPLATE/
├── config.yaml 禁止空白 Issue + 引导到 general
├── config.yaml 禁止空白 Issue + 引导到 general + 课程官网链接
└── 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 个模板)
@@ -97,10 +117,15 @@ uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework
## 自定义
如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送:
如需调整模板内容(如添加新的问题分类、修改引导文案、更新 `config.yaml` 里的链接),
直接编辑对应的 YAML 文件, 然后重新推送:
```bash
# 已有仓库原地更新(general 与各 hwNN 都要推一次)
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)。
@@ -1,8 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: 课程主页
url: https://example.com
about: 访问课程主页获取有关资源
- name: 常见问题汇总
url: https://example.com/faq
about: 提问前请先查阅常见问题汇总
- name: 提问前必读 · 提问指南
url: http://10.80.42.185/Website/qa/ask/
about: 课程官网上的提问规范与做法。不合规范的提问很可能不会得到回答
- name: 课程官网
url: http://10.80.42.185/Website/
about: 课程信息、作业说明、环境配置要求、常见问题
@@ -1,5 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: 一般性问题请到 general 仓库提问
url: https://example.com
url: "{{BASE_URL}}/{{ORG}}/general/issues/new/choose"
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
# Pytest
.pytest_tmp/
.coverage
# Secrets & credentials
+51 -24
View File
@@ -1,6 +1,6 @@
# 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
```
编辑 `.secrets.toml`, 填入实际值:
编辑 `.secrets.toml`, 填入实际值:
```toml
[default.gitea]
@@ -41,7 +41,7 @@ API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选
### 环境变量覆盖
所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖:
所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖:
```bash
export TJHLP_GITEA_URL=http://192.168.1.100:3000
@@ -56,7 +56,7 @@ tjhlp
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态
├── users
│ ├── create 从 CSV 批量创建账号(随机初始密码, 自动导出凭据 CSV)
│ ├── create 从 CSV 批量创建账号(随机密码)
│ ├── list 列出所有用户
│ └── delete 批量删除用户
├── orgs
@@ -77,9 +77,12 @@ tjhlp
├── labels
│ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label
└── stats
├── summary Issue 统计摘要
└── export 导出 Issue 数据到 CSV
├── stats
│ ├── summary Issue 统计摘要
│ └── 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
```
执行完成后会自动生成 `credentials_YYYYMMDD_HHMMSS.csv`, 包含账号、随机初始密码和处理状态。
`cmd` 可直接复制的写法:
## 典型工作流
```cmd
### 学期初始化
```bash
# 1. 检查连接
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
# 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
```
`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 团队。
### 日常管理
@@ -144,6 +156,20 @@ uv run tjhlp labels sync tjhlp-2025f/hw03
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
@@ -162,16 +188,16 @@ id,name,role
```
- `id` - 学号或工号, 同时作为 Gitea 用户名
- `name` - 姓名, 作为 Gitea 的 `full_name`
- `name` - 姓名, 作为 Gitea 的 full_name
- `role` - `student` 或 `ta`, 决定分配到哪个团队
- 邮箱自动生成为 `{id}@tongji.edu.cn`
- 初始密码由程序随机生成, `users create` 执行后会自动导出凭据 CSV
- **初始密码与用户名(学号/工号)相同**。
示例文件见 `example/members.csv`。
## 预定义 Label
通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建:
通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建:
| Label | 颜色 | 用途 |
|-------|------|------|
@@ -197,15 +223,15 @@ uv sync --extra dev
### 运行测试
```bash
uv run pytest tests/ -v --basetemp .pytest_tmp # 全部测试
uv run pytest tests/test_models.py --basetemp .pytest_tmp # 只运行模型测试
uv run pytest tests/ -k "password" --basetemp .pytest_tmp # 按名称过滤
uv run pytest tests/ -v # 全部测试
uv run pytest tests/test_models.py # 只运行模型测试
uv run pytest tests/ -k "password" # 按名称过滤
```
### 覆盖率报告
```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_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试
│ ├── test_pure_functions.py 纯函数测试
│ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试
└── src/tjhlp/
+4 -1
View File
@@ -1,5 +1,8 @@
[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"
default_org = ""
+3 -3
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError
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)
console = Console()
@@ -69,7 +69,7 @@ def create_homework(
# 推送作业 Issue Templates
console.print("\n推送 Issue Templates...")
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} 个模板文件")
# 同步 Labels
@@ -120,7 +120,7 @@ def init_templates(
cfg = get_gitea_config()
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}")
+2 -2
View File
@@ -9,7 +9,7 @@ from rich.console import Console
from tjhlp.client import GiteaClient, GiteaClientError
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)
console = Console()
@@ -86,7 +86,7 @@ def init(
console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]")
general_tpl_dir = _TEMPLATES_DIR / "general"
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} 个模板文件")
else:
console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]")
+4 -95
View File
@@ -3,8 +3,7 @@
import csv
import secrets
import string
from dataclasses import dataclass
from datetime import datetime
from datetime import UTC, datetime
from pathlib import Path
import typer
@@ -19,17 +18,6 @@ app = typer.Typer(no_args_is_help=True)
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]:
"""读取 members CSV 文件"""
records: list[MemberRecord] = []
@@ -40,45 +28,13 @@ def _read_members_csv(filepath: Path) -> list[MemberRecord]:
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")
def create_users(
file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"),
org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"),
dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"),
) -> None:
"""从 CSV 批量创建用户账号(随机初始密码, 自动导出凭据 CSV)"""
"""从 CSV 批量创建用户账号(初始密码与用户名相同)"""
if not file.exists():
console.print(f"[red]文件不存在: {file}[/red]")
raise typer.Exit(code=1)
@@ -103,8 +59,6 @@ def create_users(
return
stats = {"created": 0, "skipped": 0, "failed": 0}
# 用于记录创建结果
credential_records: list[CredentialRecord] = []
with GiteaClient(cfg) as client:
# 获取团队 ID(如果指定了组织)
@@ -115,36 +69,23 @@ def create_users(
students_team = client.get_team_by_name(org, "students")
for member in members:
# 检查用户是否已存在,仅校验用户名是否存在
# 检查用户是否已存在
existing = client.get_user(member.username)
if existing:
console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在")
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
try:
password = _generate_password()
client.create_user(
username=member.username,
password=password,
password=member.username,
email=member.email,
full_name=member.name,
must_change_password=True,
)
console.print(f" [green]创建[/green] {member.username}({member.name})")
stats["created"] += 1
message = "created"
# 添加到团队
if org:
@@ -154,46 +95,14 @@ def create_users(
client.add_team_member(team.id, member.username)
except GiteaClientError as e:
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:
console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}")
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(
f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}"
)
console.print(f"凭据已导出: {output_path}")
@app.command("list")
+4
View File
@@ -55,6 +55,10 @@ class GiteaConfig(BaseModel):
token: SecretStr
email_domain: str = "tongji.edu.cn"
default_org: str = ""
# 面向用户的访问地址(Apache 反代后的地址, 如 https://cpp.tongji.sh/QA)。
# url 是 CLI 调 API 用的地址, 可能带内部端口, 不能直接写进 Issue Template 等
# 给同学看的链接里; 留空时回退到 url。
public_url: str = ""
labels: list[LabelDef] = []
+34 -1
View File
@@ -34,11 +34,38 @@ def parse_repo(repo: str) -> tuple[str, str]:
# ---------------------------------------------------------------------------
# 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(
client: GiteaClient,
org: str,
repo: str,
template_dir: Path,
web_base: str = "",
) -> int:
"""将本地 issue template 目录推送到远端仓库, 返回推送的文件数。"""
count = 0
@@ -51,7 +78,13 @@ def push_templates(
if not filepath.is_file():
continue
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)
if existing:
+13 -94
View File
@@ -2,6 +2,7 @@
from __future__ import annotations
import csv
from pathlib import Path
from unittest.mock import MagicMock, patch
@@ -10,7 +11,6 @@ from pydantic import HttpUrl, SecretStr
from typer.testing import CliRunner
from tjhlp.cli import app
from tjhlp.client import GiteaClient, GiteaClientError
from tjhlp.config import GiteaConfig, LabelDef
from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser
@@ -104,16 +104,9 @@ class TestUsersCreateDryRun:
class TestUsersCreate:
@patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config")
def test_creates_users(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
def test_creates_users(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path):
mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient)
client = MagicMock()
client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False)
client.get_user.return_value = None # user doesn't exist
@@ -123,7 +116,6 @@ class TestUsersCreate:
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,
@@ -133,44 +125,22 @@ class TestUsersCreate:
"--file",
str(csv_file),
],
catch_exceptions=False,
)
assert result.exit_code == 0
assert "创建" in result.output
assert "凭据已导出:" in result.output
client.create_user.assert_called_once()
call_kwargs = client.create_user.call_args.kwargs
assert call_kwargs["username"] == "2659999"
assert call_kwargs["email"] == "[email protected]"
assert call_kwargs["full_name"] == "赵一伤"
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
client.create_user.assert_called_once_with(
username="2659999",
password="2659999",
email="[email protected]",
full_name="赵一伤",
must_change_password=True,
)
@patch("tjhlp.commands.users.GiteaClient")
@patch("tjhlp.commands.users.get_gitea_config")
def test_skips_existing_user(
self,
mock_get_cfg: MagicMock,
mock_client_cls: MagicMock,
mock_config: GiteaConfig,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch
):
"""
测试内容:用户已存在时,是否正常导出凭据,且凭据中包含已存在的用户名和错误信息
预期:
- 用户已存在时,凭据导出文件中包含已存在的用户名和错误信息
"""
def test_skips_existing_user(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path):
mock_get_cfg.return_value = mock_config
client = MagicMock(spec=GiteaClient)
client = MagicMock()
client.__enter__ = MagicMock(return_value=client)
client.__exit__ = MagicMock(return_value=False)
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.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,
)
result = runner.invoke(app, ["users", "create", "--file", str(csv_file)])
assert result.exit_code == 0
assert "跳过" in result.output
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
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
_EXIT_EXCEPTIONS = (SystemExit, Exception)
@@ -103,3 +110,44 @@ class TestComputeIssueStats:
]
stats = compute_issue_stats(issues)
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"