仿 Dress 的照片投稿仓库, 适配自建 Gitea 平台 git.xhmcl.com: - README / GUIDE (PR 教程) / CONTRIBUTING / Q&A / EXIF / PARTIAL_CLONE (中英双语) - A-Z + # 首字母目录结构 - .gitea: PR 模板、维护者名单、7 个纯 bash + API 的 Actions 工作流 (可选功能) Co-Authored-By: Claude Code <noreply@anthropic.com>
13 KiB
🌟 新手指南(PR 教程)
欢迎来到小南娘项目!这份指南将帮助你完成第一次合并请求(Pull Request,简称 PR)。
本项目托管在自建平台 git.xhmcl.com,基于 Gitea。流程和 GitHub 基本相同,但按钮位置和个别叫法略有差异,下文按 Gitea 的界面来写。
重要:本平台只开放 HTTP(S),没有 SSH。 所有克隆和推送都使用
https://地址,你不需要配置任何 SSH Key。
📋 提交流程概览
Fork(复刻)仓库 → 添加你的照片 → 提交 Commit → 发起合并请求(PR)→ 等待审核合并
第一步:Fork 仓库
Fork(复刻) = 把别人的仓库「复制」一份到你自己的账号下,让你可以自由修改喵,不会影响原项目喵!
- 打开 小南娘仓库页面
- 点击页面右上角的 Fork(复刻) 按钮
- 这会在你的账号下创建一份仓库副本,地址类似
https://git.xhmcl.com/<你的用户名>/dress-pr
第二步:添加你的照片
Commit = 给你的修改拍一张「快照」,记录你改了什么内容,每次 Commit 都会生成一条历史记录喵!
方法 A:直接在网页上传(最简单,不需要安装任何东西)
- 进入你 Fork 后的仓库页面(
https://git.xhmcl.com/<你的用户名>/dress-pr) - 根据计划使用的个人文件夹名称选择对应的首字母目录(如
Yueosa进入Y,数字或符号开头则进入#) - 点击右上角的 +(添加文件)→ 新建文件(New File)
- 在文件名栏输入
你的文件夹名/README.md(如Yueosa/README.md),这会自动创建文件夹;文件夹名无需与你的账号 ID 相同 - 在文件中随意写一些内容(如自我介绍)
- 点击 提交更改(Commit Changes)
- 再次点击 + → 上传文件(Upload File),将你的照片上传到刚创建的文件夹中
- 点击 提交更改(Commit Changes)
方法 B:使用 Git 命令行
Clone = 把远程仓库下载到本地电脑。 Push = 把本地的 Commit 上传同步到远程仓库(你的 Fork)。
# 1. 克隆你 Fork 的仓库(本平台只支持 HTTP 地址)
# 由于仓库 commit 历史较多,使用 --depth 1 仅拉取最近一次提交
git clone --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr
如果你觉得仓库图片较多、普通克隆太慢,可以使用部分克隆代替上面的命令,只下载自己的目录:
git clone --filter=blob:none --sparse --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr
git sparse-checkout set '<首字母>/<你的文件夹名>'
部分克隆不会影响正常提交和 PR。目录管理、完整历史和恢复完整仓库的方法请阅读部分克隆指南。
克隆完成后,创建你的文件夹并添加照片:
# 2. 创建你的文件夹并添加照片
# <首字母> 应与 <你的文件夹名> 的首字符对应;数字或符号开头时使用 #
mkdir -p <首字母>/<你的文件夹名>
cp /path/to/your/photos/* <首字母>/<你的文件夹名>/
# 3. 提交更改
git add .
git commit -m "Add photos for <你的文件夹名>"
# 4. 推送到你的 Fork
git push origin main
🔑 推送时需要认证:本平台没有 SSH,推送时 Git 会要求输入用户名和密码。密码不是你的登录密码,而是「访问令牌(Access Token)」:
- 点击右上角头像 → 设置(Settings) → 应用(Applications)
- 在「管理访问令牌 / Access Tokens」一栏点击 生成令牌(Generate Token)
- 令牌名称随意填写;权限勾选仓库读写(Repository: read-write,若平台按细粒度列出,勾选
repository下的读写权限)- 生成后立即复制保存,它只会显示这一次
- 推送时:用户名填你的账号名,密码粘贴这个令牌
第三步:发起合并请求(Pull Request)
合并请求(Pull Request,PR) = 向原仓库的维护者提出申请:「我在我的 Fork 里做了一些修改,请把它们合并到原项目里吧喵!」
- 回到你 Fork 的仓库页面
- 点击 合并请求(Pull Requests) 标签 → 新建合并请求(New Pull Request)
- 如果刚推送完,页面上通常会出现一条提示横幅,直接点上面的按钮即可
- 确认合并方向:
- 目标(base):
xhgit/dress-pr的main分支 - 源(head):你的 Fork 仓库里你刚推送的分支
- 目标(base):
- 填写 PR 描述:
- 平台会自动填入仓库提供的 PR 模板
- 请勿删除模板顶部的
<!-- pr-type: images -->标记行 - 在模板的「自查清单 / Checklist」中逐项勾选(把
[ ]改成[x]) - 本次不是交照片?把
pr-type改为ci_wf/docs/others,并按提示勾选清单
- 点击 创建合并请求(Create Pull Request)
第四步:等待审核
提交照片类 PR 后,需要检查以下事项:
- 📋 PR 内容:自查清单是否齐全并全部勾选、是否包含图片变更、文件是否位于对应的
A-Z/#/昵称/目录下 - 📏 文件大小:图片是否在 1 MiB(1 MB)以内
- 🔒 EXIF 信息:图片是否包含高敏感元数据(主要是 GPS 坐标及地址类字段)
如果平台启用了 Gitea Actions,以上检查会自动运行,检查结果直接显示在 PR 页面的「检查 / Checks」区域;未通过时 PR 下会留下评论说明原因。 如果平台暂未启用 Actions,则由维护者人工检查,同样会在评论里说明原因。
检查未通过时,按提示修改后重新 push(网页上传则重新提交),检查会自动重跑。
如果平台启用了 Actions,还可以在评论区发送 /auto-fix 命令自动处理:将图片压缩到 1 MiB 以内,并去除全部 EXIF(比检查更彻底)。若你不希望文件被改动,请自行处理好后再推送。
维护者审核通过后,你的 PR 就会被合并。恭喜你完成了一次开源贡献!🎉
⚠️ 提交前请注意
- 压缩图片 — 确保每张图片小于 1 MiB。可以使用 TinyPNG 等在线工具压缩。
- 移除高敏感 EXIF 信息 — 最重要的是删除 GPS 坐标,它能精确暴露你的拍摄地点。照片还可能携带地址、联系方式等信息。详见 EXIF 字段说明 和 贡献准备中的清理方法。
- 正确命名文件夹 — 使用有意义的文件夹名(无需与账号 ID 相同),并按其首字符放在对应的
A-Z/#目录下。 - 原创图片 — 只提交你自己的照片,不接受盗图。
- 只修改自己的文件夹 — 请不要改动他人的文件夹或其他项目文件,避免给维护者带来不必要的麻烦。
- 文件名避免中文和空格 — 文件名中的中文字符或空格可能导致部分系统无法正常显示或下载,请尽量使用英文字母、数字和连字符。
- 推送用令牌,不用登录密码 — 命令行推送时密码位置填访问令牌(见第二步方法 B 的说明)。
🔗 参考链接
仓库 Workflow 流程(可选功能)
⚠️ 本节内容依赖平台启用 Gitea Actions 并注册至少一个 Ubuntu runner。当前未启用时,以下自动化不运行,检查由维护者人工完成。工作流文件位于 .gitea/workflows/。
一、工作流体系总览
flowchart TD
ev1(["PR 开启 / 更新 / 重开 / 编辑"]) --> PRGRP
ev2(["PR 评论含指令"]) --> CMTGRP
ev3(["定时任务 每日 11:00 UTC"]) --> stale["Mark Stale<br/>过期 PR 标记关闭"]
subgraph PRGRP["PR 触发类 pull_request_target"]
greetings["Greetings<br/>首次 PR 欢迎"]
check_pr_content["Check PR Content<br/>清单+类型+目录"]
check_file_size["Check File Size<br/>图片 ≤ 1 MiB"]
check_exif["Check EXIF<br/>敏感元数据检查"]
end
subgraph CMTGRP["评论触发类 issue_comment"]
auto_fix["Auto-fix<br/>/auto-fix 修复图片"]
fast_forward["Fast-forward<br/>/fast-forward 合并"]
end
check_file_size -->|"评论提示"| auto_fix
check_exif -->|"评论提示"| auto_fix
auto_fix -.->|"push 后重跑"| check_file_size
auto_fix -.->|"push 后重跑"| check_exif
二、图片 PR 完整生命周期
flowchart TD
start(["贡献者提交 PR"]) --> prt["pull_request_target 触发"]
prt --> greet["Greetings<br/>首次贡献欢迎"]
prt --> content["Check PR Content"]
content --> c1{"自查清单<br/>全部勾选?"}
c1 -->|否| failc["评论 + 检查失败"]
c1 -->|是| c2{"pr-type 规则"}
c2 -->|"images 需有图片变更<br/>且目录归入 A-Z/#/昵称"| pass["检查通过"]
c2 -->|"ci_wf 变更限 .gitea/"| pass
c2 -->|"docs/others 仅查清单"| pass
c2 -->|不符合| failc
prt --> size["Check File Size"]
size --> s1{"图片均 ≤ 1 MiB?"}
s1 -->|是| pass
s1 -->|否| fails["评论超限列表 + 失败"]
prt --> exif["Check EXIF"]
exif --> e1{"含 GPS / 地址<br/>联系方式等敏感 EXIF?"}
e1 -->|否| pass
e1 -->|是| faile["评论敏感列表 + 失败"]
failc --> manual["作者手动修复并重新 push"]
manual --> prt
fails --> cmd["维护者或 PR 作者<br/>回复 /auto-fix"]
faile --> cmd
cmd --> af1["去除全部 EXIF"]
af1 --> af2{"压缩至 ≤ 1 MiB?"}
af2 -->|"成功"| af3["提交并 push 回 PR 分支"]
af2 -->|"20 次仍失败"| af4["整体回滚不 push<br/>评论提示手动修复"]
af3 --> prt
pass --> review["维护者审核"]
review --> ff["回复 /fast-forward<br/>变基合并 保留原始提交"]
ff --> done(["合并完成"])
prt -.->|"长期无活动"| stale["每日定时扫描<br/>标记 stale 7 天未回应则关闭"]
三、工作流一览
| 工作流 | 文件 | 触发方式 | 主要行为 |
|---|---|---|---|
| Greetings | greetings.yml |
pull_request_target |
对首次贡献者的 PR 发送中英双语欢迎评论 |
| Check PR Content | check_pr_content.yml |
pull_request_target(opened / synchronize / reopened / edited) |
所有类型 PR 须勾选自查清单;images 须有图片变更且目录符合 A-Z/#/昵称/ 结构;ci_wf 变更须全部在 .gitea/ 内;未识别的 pr-type 报错 |
| Check File Size | check_file_size.yml |
pull_request_target(opened / synchronize / reopened) |
仅 images 类 PR:变更图片须全部 ≤ 1 MiB,超限则评论列出文件并提示 /auto-fix,检查失败 |
| Check Image EXIF Data | check_exif.yml |
pull_request_target(opened / synchronize / reopened,同 PR 并发取消) |
仅 images 类 PR:下载变更图片,用 exiftool 检查 GPS、地址、联系方式等高敏感 EXIF;普通摄影参数不拦截;命中则评论并提示 /auto-fix |
| Auto-fix Image Files | auto_fix.yml |
issue_comment(评论以 /auto-fix 开头,且为维护者或 PR 作者) |
检出 PR 分支 → exiftool 清除全部 EXIF → 循环压缩(jpegoptim / pngquant / optipng / ImageMagick,最多 20 次)至 ≤ 1 MiB → push 回 PR 分支触发检查重跑;压缩失败则整体回滚不 push 并评论说明 |
| Fast-forward for PR | fast-forward.yml |
issue_comment / pull_request_review_comment(评论含 /fast-forward) |
校验评论者有 write 权限后调用平台 API 以变基(rebase)方式合并 PR,保留原始提交与签名;合并失败时评论说明原因 |
| Mark Stale Issues and PRs | stale.yml |
schedule(cron: 0 11 * * *) |
仅针对 PR:长期无活动先标记并提醒 7 天内回应,仍无回应则关闭(issue 不处理) |
说明:
- pr-type 通过 PR 正文中的
<!-- pr-type: xxx -->标签识别,取值为images / ci_wf / docs / others,缺省按images处理。- 所有工作流均为纯 shell + 平台 API 实现,不依赖任何第三方 action,无需从 GitHub 拉取任何内容。
- 若你的 Gitea 版本不支持
pull_request_target事件,请把工作流里的pull_request_target改为pull_request。/auto-fix需要把图片 push 回 PR 分支,请预先在仓库「设置 → Actions → Secrets」中配置BOT_USER与BOT_TOKEN(一个有 Fork 仓库写权限的账号令牌)。未配置时/auto-fix会提示无法推送。