QQgit/README.md

91 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# QQGit · 极简蓝白 ins 风外观定制
> 目标实例:`https://git.qyhhh.top`(`Gitea 1.21.11`,二进制 `/usr/local/bin/gitea`,运行用户 `git:git`)
> 本仓库是**外观定制的工作目录(staging)**。所有改动先在这里做出来、经确认后再复制进 `/var/lib/gitea/custom`。
当前状态:**`v1.0-live` 已上线**(2026-11-03 部署到 `https://git.qyhhh.top`,`DEFAULT_THEME = qq-auto`,旧主题全部保留可切回)。
## 一、铁律(不可违反)
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 --yes`。
`deploy.sh` 不加 `--yes` 时只做预演,不会动线上任何文件。
3. **线上基线可回滚**:部署前自动打包备份到 `/var/backups/gitea-custom-<时间戳>.tar.gz`,
`scripts/rollback.sh` 可一键还原。
4. **视觉铁律**:无文字(No text)、蓝白配色、**禁止绿色**、大量留白。
## 二、视觉语言
| 项目 | 规格 |
| --- | --- |
| Logo | 「蓝白 Git 节点 Q」:浅蓝圆章 + 纯白负空间 Git 分支轨道,3 颗环上 Commit 空心节点 + 环内节点跨环分叉出 Q 的尾巴 |
| 日间色 | 圆章 `#60A5FA`,轨迹 `#FFFFFF` |
| 夜间色 | 圆章 `#38BDF8`,轨迹 `#F8FAFC`(低眩光,仅调明度,符号完全一致) |
| 圆外 | **100% 透明(Alpha=0)**,任何顶栏底色下都无白边方框 |
| 主色 | 浅色 `#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 原件含 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/header.tmpl、custom/footer.tmpl、home.tmpl
│ └── public/assets/ # css(qq-ui + 3 主题)/ img(Logo 全套)/ fonts
├── preview/ # 离线可视化预览画廊(本地打开即可看效果,无需线上改动)
├── scripts/ # build_theme.py / audit_colors.py / deploy.sh / rollback.sh
├── docs/DEPLOY.md # 部署与回滚手册
└── docs/TODO.md # 分阶段任务清单(本仓库的持久化 todo)
```
## 四、看预览(不碰线上)
浏览器直接打开 `preview/index.html` 即可:
- 右上角胶囊切换 **浅色 / 自动 / 深色**,同一份标记实时换肤;
- 页面依次展示:首页 hero + 三卡、仓库列表、仓库文件页 + 代码块、按钮/标签/输入框组件、
**Logo 在 `#FFFFFF` / `#0D1117` 顶栏上的无白边校验**;
- 预览页额外使用 `custom/public/assets/css/*` 与 `fonts/*`,所以看到的就是线上会生效的资源。
## 五、标准工作流
```bash
# 1) 开发(只动 custom/ 与 preview/)
# 改配色只需动 scripts/build_theme.py 顶部的常量,然后:
python3 scripts/build_theme.py && python3 scripts/audit_colors.py
# 2) 打候选版本,等批准
git tag v1.0-rc1
# 3) 批准后部署(先备份,再同步、修权限、重启)
./scripts/deploy.sh # 预演,安全
./scripts/deploy.sh --yes # 真部署
# 4) 需要撤销时
./scripts/rollback.sh --list
./scripts/rollback.sh /var/backups/gitea-custom-<时间戳>.tar.gz
```
## 六、版本标签约定
| `v1.0-rc2` | 品牌定名 QQGit(APP_NAME 已改,页签标题实测生效),口号「自己的代码,自己的地方。」 |
| 标签 | 含义 |
| --- | --- |
| `v0.0-baseline` | 线上原始状态 + 官方 1.21.11 模板快照 |
| `v1.0-rc2` | 工作目录候选版:Logo 全套 + 三主题 + 模板钩子 + 预览页,**未上线** |
| `v1.0-live` | 已部署到线上并通过验收(当前线上版本) |
## 七、上传限制(现状记录,不在本次改动范围)
`app.ini` 中 `[picture]` 段已调大:`AVATAR_MAX_FILE_SIZE = 52428800`、`AVATAR_MAX_WIDTH/HEIGHT = 4096`。