# QQGit · 极简蓝白 ins 风外观定制 > 目标实例:`https://git.qyhhh.top`(`Gitea 1.21.11`,二进制 `/usr/local/bin/gitea`,运行用户 `git:git`) > 本仓库是**外观定制的工作目录(staging)**。所有改动先在这里做出来、经确认后再复制进 `/var/lib/gitea/custom`。 当前状态:**`v1.0-rc2` 候选版已就绪,等 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 --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`。