Files
tjhlp-gitea/customization/preview/preview.sh
T
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

199 lines
8.7 KiB
Bash
Executable File

#!/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