chore(rc1): 补齐 rollback.sh、预览自检脚本,README 补看预览与部署流程
This commit is contained in:
parent
faf043e73e
commit
ec180e1836
57
README.md
57
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`。
|
||||
|
|
|
|||
|
|
@ -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())
|
||||
|
|
@ -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 运行中"
|
||||
Loading…
Reference in New Issue