Safe Haven 开发者提交流程，Web 门户加 .safehaven 验证文件

两种开发者身份

Safe Haven 有两种开发者身份：

• 已验证开发者：通过 Web 门户注册，完成 .safehaven 文件握手验证，提交的应用自动标记为 verified_source
• 社区开发者：没有通过验证握手，提交的应用会被标记为 unverified，需要原始开发者来认领

Web 管理门户

开发者管理自己的应用和版本的地方：store.colourswift.com 的开发者后台。注册并登录后可以：

• 创建新应用条目
• 编辑应用描述、截图、标签
• 上传新 APK 版本
• 切换自动 / 手动提交模式
• 查看版本历史和扫描记录
• 设置开发者头像和展示名

v2.0.9-beta.1 的更新里提到："Refracted the developer screen for better readability"（重构了开发者界面）和"Added the ability to set a profile picture and change your name"（新增头像和名字编辑）。

注册一个新应用

第一步：创建条目

在管理门户里点"新建应用"，填写基本信息：

• 显示名（Name）
• 简短描述（Summary）
• 完整描述（Description）
• 包名（如果还不知道，可以先留空占位，扫描管线会从 manifest 里提取真实包名）
• 源码仓库地址（GitHub / GitLab / Codeberg）
• 分类（十个固定分类里选一个）
• 标签（Keywords）
• 应用图标和最多六张截图

填完后 Safe Haven 生成一个唯一仓库验证 token，展示给你。这个 token 用于第二步的 .safehaven 文件。

第二步：放 .safehaven 文件完成验证

在你的源码仓库根目录（不是子目录）创建一个叫 .safehaven 的文件，文件内容就是刚才 Safe Haven 给你的 token。

# Linux / macOS
echo "your_safehaven_token_here" > .safehaven

# Windows PowerShell
Set-Content -Path .safehaven -Value "your_safehaven_token_here" -NoNewline

提交并推送到远程仓库。Safe Haven 后台会定期（通常几小时内）去抓这个文件，比对 token。比对成功 → 应用条目的 trustLevel 变成 verified_source。

第三步：上传 APK 版本

应用条目创建好后，可以上传 APK 了。流程：

1. 管理门户点"上传新版本"
2. 后端生成一个 AWS Signature Version 4 presigned PUT URL，有效期 15 分钟
3. 你直接用 PUT 请求把 APK 上传到这个 URL（不需要经过 Safe Haven 服务器中转）
4. 上传完成后，后端检测到文件到达 staging 临时目录，状态机切换到 pending_scan
5. safehaven-scanner 服务从 staging 拉 APK 跑完整扫描管线
6. 扫描通过 → 状态机进入 pending_review，等待自动批准（见下）
7. 扫描未通过 → 状态机进入 rejected，上传失败

presigned URL 为什么要中转

开发者不直接往生产存储桶里写文件，必须先到 staging 临时目录。这样做的好处：

• 扫描管线有机会拦截恶意 APK，防止直接进生产目录
• 上传和处理完全解耦——上传 50MB APK 可能要 2 分钟，扫描要 10 秒，先到 staging 让上传和扫描并行
• staging 目录对客户端不可见，用户搜不到正在上传的 APK

presigned PUT URL 有效期 15 分钟，下载 URL 有效期 5 分钟，图片 URL 有效期 7 天——不同资源不同的过期时间。

三种提交模式

自动提交（默认）

Safe Haven 的统一 Poller 每 6 小时检查一次应用的上游仓库（GitHub Release、GitLab Tags、F-Droid 索引等）。如果发现新版本：

• 自动下载 APK → 走扫描管线 → 自动上架 → 自动过 pending_review → 进公开目录

整个过程不需要开发者动手，和上游仓库保持同步。

手动提交

切换到手动模式后，统一 Poller 跳过这个应用，不会自动拉新版本。开发者必须自己在管理门户里手动上传。

适合版本发布节奏需要人工控制的场景——比如想先内部测试几天再上架，或者想自己手动触发某些操作。

Safe Haven 自更新（特殊）

Safe Haven 客户端自己的提交有特权路径——pending_review 阶段完全跳过，扫描通过后立即进入 live 状态。这是一个硬编码的特殊处理，目的是让客户端自己的更新能最快速度触达用户。

待审核（pending_review）怎么自动通过

扫描管线通过的 APK 状态机进入 pending_review。这个状态不是等人手动审核——Safe Haven 有一个 cron 服务后台跑，周期性检查 pending_review 条目：

• 如果条目在 review 状态停留超过一定时间且没有产生错误，自动批准进 live
• Safe Haven 自更新的提交绕过 review，扫描通过直接进 live
• 如果扫描阶段产生错误，提交不会进入 review，直接进 rejected 或标记待处理

图片上传规则

Safe Haven 对应用图片有硬性约束：

• 格式：PNG / JPEG / WebP
• 单张 ≤ 2 MB
• 每个应用：1 个图标 + 最多 6 张截图
• 图标在上传时会被自动归一化处理（统一尺寸和格式）
• 如果开发者没上传图标，扫描管线会尝试从 APK 里提取一个

Access Control 七层

Safe Haven 后端的 HTTP API 用七层访问控制来保护不同 endpoint：