From ec180e18364c772cd08b795a3a28237cbbf590ef Mon Sep 17 00:00:00 2001 From: QQ Date: Mon, 2 Nov 2026 18:25:07 +0800 Subject: [PATCH] =?UTF-8?q?chore(rc1):=20=E8=A1=A5=E9=BD=90=20rollback.sh?= =?UTF-8?q?=E3=80=81=E9=A2=84=E8=A7=88=E8=87=AA=E6=A3=80=E8=84=9A=E6=9C=AC?= =?UTF-8?q?=EF=BC=8CREADME=20=E8=A1=A5=E7=9C=8B=E9=A2=84=E8=A7=88=E4=B8=8E?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 57 ++++++++++++++++++++++++++-------------- scripts/check_preview.py | 54 +++++++++++++++++++++++++++++++++++++ scripts/deploy.sh | 0 scripts/rollback.sh | 33 +++++++++++++++++++++++ 4 files changed, 125 insertions(+), 19 deletions(-) create mode 100644 scripts/check_preview.py mode change 100644 => 100755 scripts/deploy.sh create mode 100755 scripts/rollback.sh diff --git a/README.md b/README.md index dbc62b0..6b33e58 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,18 @@ > 目标实例:`https://git.qyhhh.top`(`Gitea 1.21.11`,二进制 `/usr/local/bin/gitea`,运行用户 `git:git`) > 本仓库是**外观定制的工作目录(staging)**。所有改动先在这里做出来、经确认后再复制进 `/var/lib/gitea/custom`。 +当前状态:**`v1.0-rc1` 候选版已就绪,等 QQ 在预览页验收;线上未做任何修改。** + ## 一、铁律(不可违反) 1. **只改外观,不改源码**:唯一允许的手段是 Gitea 官方的 `custom/` 覆盖机制—— `custom/templates/*.tmpl`(模板覆盖 / 注入钩子)、`custom/public/assets/css|js|img|fonts`(静态资源)。 **绝不**修改 `/usr/local/bin/gitea` 二进制、**绝不**重新编译、**绝不**改 `/var/lib/gitea` 以外的源码树。 -2. **先工作目录、后线上**:`custom/` 只是「待发布副本」;只有拿到明确批准后才执行 `scripts/deploy.sh`。 -3. **线上基线可回滚**:部署前自动打包备份,`scripts/rollback.sh` 可一键还原。 -4. **视觉铁律**:无文字(No text)、蓝白配色、**禁止绿色**(告别 Gitea 原版绿茶杯)、大量留白。 +2. **先工作目录、后线上**:`custom/` 只是「待发布副本」;只有拿到明确批准后才执行 `scripts/deploy.sh --yes`。 + `deploy.sh` 不加 `--yes` 时只做预演,不会动线上任何文件。 +3. **线上基线可回滚**:部署前自动打包备份到 `/var/backups/gitea-custom-<时间戳>.tar.gz`, + `scripts/rollback.sh` 可一键还原。 +4. **视觉铁律**:无文字(No text)、蓝白配色、**禁止绿色**、大量留白。 ## 二、视觉语言 @@ -20,50 +24,65 @@ | 日间色 | 圆章 `#60A5FA`,轨迹 `#FFFFFF` | | 夜间色 | 圆章 `#38BDF8`,轨迹 `#F8FAFC`(低眩光,仅调明度,符号完全一致) | | 圆外 | **100% 透明(Alpha=0)**,任何顶栏底色下都无白边方框 | -| 主色 | 浅蓝 `#60A5FA` / `#0EA5E9` / 深色模式 `#38BDF8` | -| 字体 | `JetBrains Mono` / `JetBrains Mono Nerd Font`(代码、Hash、分支名优先) | -| 圆角 | `10px` 卡片 / 输入框,克制的呼吸留白 | +| 主色 | 浅色 `#3B82F6`(hover `#2563EB` / active `#1D4ED8`),深色 `#38BDF8`(hover `#7DD3FC`) | +| 台面色 | 浅色 body `#FFFFFF` / header `#F8FAFC`;深色 body `#0D1117` / box `#161B22` | +| 字体 | `JetBrains Mono`(wght 400/500/700,woff2 本地内置,不走 CDN) | +| 圆角 | `8px` | ## 三、目录结构 ``` . ├── baseline/ # 线上基线快照(部署前的原始状态,回滚依据) -│ ├── app-ini/ui-section.txt # [ui] 段落快照;app.ini 原件含凭据,已 gitignore +│ ├── app-ini/ui-section.txt # [ui] 段落快照;app.ini 原件含 SMTP 凭据,已 gitignore │ └── custom/ # /var/lib/gitea/custom 的完整副本 ├── upstream-templates-1.21.11/ # 从二进制导出的官方原生模板(只读参考,防跨版本 DOM 错位) +├── vendor/ # 官方 index.css / theme-auto.css 原件(变量派生源,留档) ├── design-assets/ # Logo 设计原图与决策记录 ├── custom/ # ★ 待发布的覆盖层(部署时整体同步到线上 custom/) -│ ├── templates/ # 模板覆盖 + custom/ 注入钩子 -│ └── public/assets/ # css / js / img / fonts +│ ├── templates/ # custom/header.tmpl、custom/footer.tmpl、home.tmpl +│ └── public/assets/ # css(qq-ui + 3 主题)/ img(Logo 全套)/ fonts ├── preview/ # 离线可视化预览画廊(本地打开即可看效果,无需线上改动) -└── scripts/ # deploy.sh / rollback.sh +├── scripts/ # build_theme.py / audit_colors.py / deploy.sh / rollback.sh +└── docs/DEPLOY.md # 部署与回滚手册 ``` -## 四、标准工作流 +## 四、看预览(不碰线上) + +浏览器直接打开 `preview/index.html` 即可: + +- 右上角胶囊切换 **浅色 / 自动 / 深色**,同一份标记实时换肤; +- 页面依次展示:首页 hero + 三卡、仓库列表、仓库文件页 + 代码块、按钮/标签/输入框组件、 + **Logo 在 `#FFFFFF` / `#0D1117` 顶栏上的无白边校验**; +- 预览页额外使用 `custom/public/assets/css/*` 与 `fonts/*`,所以看到的就是线上会生效的资源。 + +## 五、标准工作流 ```bash -# 1) 本地开发(只动 custom/ 与 preview/) -git checkout -b feat/xxx +# 1) 开发(只动 custom/ 与 preview/) +# 改配色只需动 scripts/build_theme.py 顶部的常量,然后: +python3 scripts/build_theme.py && python3 scripts/audit_colors.py # 2) 打候选版本,等批准 git tag v1.0-rc1 -# 3) 批准后部署(内部会先备份,再同步、修权限、重载) -sudo ./scripts/deploy.sh +# 3) 批准后部署(先备份,再同步、修权限、重启) +./scripts/deploy.sh # 预演,安全 +./scripts/deploy.sh --yes # 真部署 # 4) 需要撤销时 -sudo ./scripts/rollback.sh +./scripts/rollback.sh --list +./scripts/rollback.sh /var/backups/gitea-custom-<时间戳>.tar.gz ``` -## 五、版本标签约定 +## 六、版本标签约定 | 标签 | 含义 | | --- | --- | | `v0.0-baseline` | 线上原始状态 + 官方 1.21.11 模板快照 | -| `v1.0-rcN` | 工作目录候选版本,等待确认 | +| `v1.0-rc1` | 工作目录候选版:Logo 全套 + 三主题 + 模板钩子 + 预览页,**未上线** | | `v1.0-live` | 已部署到线上并通过验收 | -## 六、上传限制(现状记录,不在本次改动范围) +## 七、上传限制(现状记录,不在本次改动范围) `app.ini` 中 `[picture]` 段已调大:`AVATAR_MAX_FILE_SIZE = 52428800`、`AVATAR_MAX_WIDTH/HEIGHT = 4096`。 diff --git a/scripts/check_preview.py b/scripts/check_preview.py new file mode 100644 index 0000000..b51b19c --- /dev/null +++ b/scripts/check_preview.py @@ -0,0 +1,54 @@ +"""预览页自检:确认 preview / qq-ui / 模板之间没有对不上的 CSS 变量或类名。 + +用法:python3 scripts/check_preview.py +""" +import pathlib +import re +import sys + +ROOT = pathlib.Path(__file__).resolve().parent.parent +CSS = ROOT / 'custom/public/assets/css' +OWN = {'--qq-font-mono', '--disc', '--mark'} + + +def vars_in(p): + out = set() + for v in re.findall(r'--[a-z0-9-]+', pathlib.Path(p).read_text()): + if v.strip('-') and not v.endswith('-'): + out.add(v) + return out + + +def main(): + used = (vars_in(ROOT / 'preview/preview.css') + | vars_in(ROOT / 'preview/index.html') + | vars_in(CSS / 'qq-ui.css')) + light = vars_in(CSS / 'theme-qq-light.css') + dark = vars_in(CSS / 'theme-qq-dark.css') + + ok = True + for name, defined in (('light', light), ('dark', dark)): + missing = sorted(used - defined - OWN) + print(f'{name:5s} 缺失变量: {missing if missing else "无"}') + ok = ok and not missing + + tmpl = (ROOT / 'custom/templates/home.tmpl').read_text() + classes = sorted({c for group in re.findall(r'class="([^"]+)"', tmpl) for c in group.split()}) + ui = (CSS / 'qq-ui.css').read_text() + for cls in ('qq-home-cards', 'qq-home-card', 'qq-footer', 'page-content'): + has = ('.' + cls) in ui + print(f'qq-ui 含 .{cls}: {has}') + ok = ok and has + + auto = (CSS / 'theme-qq-auto.css').read_text().replace(' ', '') + has_media = '@media(prefers-color-scheme:dark)' in auto + print('theme-qq-auto 含日夜媒体查询:', has_media) + ok = ok and has_media + + print('模板类名:', ' '.join(classes)) + print('\n结论:', '通过' if ok else '有问题') + return 0 if ok else 1 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/scripts/deploy.sh b/scripts/deploy.sh old mode 100644 new mode 100755 diff --git a/scripts/rollback.sh b/scripts/rollback.sh new file mode 100755 index 0000000..c56db3f --- /dev/null +++ b/scripts/rollback.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# ============================================================================= +# rollback.sh —— 从 /var/backups 的 tar 包还原线上 custom/ 与 app.ini +# +# ./scripts/rollback.sh # 列出可用备份 +# ./scripts/rollback.sh <备份文件> # 还原指定备份(会再问一次 y/N) +# ./scripts/rollback.sh --list # 同上,列出 +# ============================================================================= +set -euo pipefail + +BACKUP_DIR="/var/backups" +DST_CUSTOM="/var/lib/gitea/custom" + +if [ "${1:-}" = "" ] || [ "${1:-}" = "--list" ]; then + echo "可用备份(新的在上):" + ls -1t "$BACKUP_DIR"/gitea-custom-*.tar.gz 2>/dev/null || echo " (没有找到备份)" + echo + echo "还原用法:./scripts/rollback.sh $BACKUP_DIR/gitea-custom-<时间戳>.tar.gz" + exit 0 +fi + +BACKUP="$1" +[ -f "$BACKUP" ] || { echo "备份不存在:$BACKUP" >&2; exit 1; } + +echo "将把 $BACKUP 解包覆盖 /var/lib/gitea/custom 与 /etc/gitea/app.ini" +read -r -p "确认还原?(y/N) " ans +[ "$ans" = "y" ] || [ "$ans" = "Y" ] || { echo "已取消"; exit 0; } + +sudo tar xzf "$BACKUP" -C / +sudo chown -R git:git "$DST_CUSTOM" +sudo systemctl restart gitea +sleep 2 +systemctl is-active gitea && echo "还原完成,gitea 运行中"