Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

7.0 KB
Raw Blame

安全说明

Peach is a single-user, self-hosted application: one deployment serves one person, with no accounts, roles or tenant isolation. The threat model covers one thing only: other devices on the same LAN being let in by accident. Browser access is protected by an optional access password (scrypt-hashed, login attempts limited per client); scripts use an internal token under <data root>/secrets/, and peach serve refuses to start on a non-loopback address when it has no token. Source deployments serve HTTPS with a self-signed local CA (only the CA certificate is ever distributed); the standalone Windows package serves plain HTTP on the LAN. Do not expose Peach to the public internet through port forwarding or a reverse proxy: there is no audit log and no second factor. The built-in Cloudflare entry refuses to start without an access password and is meant for temporary previews. Report vulnerabilities through the repository's GitHub Security tab (Private vulnerability reporting), not a public issue. The rest of this document is in Chinese.

威胁模型

Peach 是单人自托管应用:一个部署只服务一个人,没有账号体系、没有权限分级,也没有多租户隔离。

Linux 无桌面部署的配置管理接受经过鉴权的回环与私有网络连接,拒绝公网、链路本地、保留地址和携带转发头的管理请求。地址分类使用 Python 标准库。容器端口默认发布到宿主机回环,部署方式见 Docker 部署。

能打开 Peach 的人,就能看到整个馆藏,也能做任何修改。Peach 只防一件事:同一局域网里的其他设备被无意放进来。多人共用和云端托管不在考虑范围内。

访问密码

访问密码决定浏览器打开 Peach 时要不要登录。

  • 首次设置页可以设访问密码,也可以留空。之后在配置页「网络与访问 → 访问密码」里修改或关闭。
  • 不设密码时,任何能连到 Peach 的设备打开地址就能进入。 局域网里有其他人时,请务必设置。
  • 密码长度 8–256 个字符。修改密码需要输入当前密码;关闭密码还要勾选确认访问范围。
  • 登录时勾选「保持登录」可保持 30 天;不勾选只在这次浏览器会话内有效,最长 12 小时。刷新页面不会延长有效期。
  • 修改密码后,其他浏览器的登录全部失效,当前设备保持登录。
  • 「网络与访问 → 已登录的设备」列出登录过的浏览器;设备丢失时,在运行 Peach 的电脑上撤销那一台即可,其他设备不受影响。设备记录只存登录令牌的摘要和来源网段。
  • 同一来源每分钟最多尝试登录 10 次,超出后要等一分钟。
  • 密码以 scrypt 哈希保存在本机 <Peach 数据目录>/secrets/access.json,不进数据库,也不参与任何同步。

Docker 部署的首次设置与访问设置只接受宿主机或局域网来源,也可以用 PEACH_ACCESS_PASSWORD 在启动时预设,见 ADR-0149。其他没有 access.json 的已有部署,登录页使用下面的访问口令。

访问口令

访问口令供脚本和 API 调用使用,和访问密码是两套凭据。

  • 口令保存在 <Peach 数据目录>/secrets/auth-token,由 peach init 自动生成。
  • 在运行 Peach 的电脑上,配置页「网络与访问 → 访问口令」可以更换口令,立即生效。新口令只在更换的那一次响应里显示,配置读取不返回口令。peach token 查看口令;peach token --rotate 也能换,但要重启服务才生效。
  • 换口令会让旧口令立即失效。用访问密码登录的浏览器不受影响;没设访问密码的部署,用旧口令登录的其他浏览器全部退出,当前浏览器保持登录。口令由 --token 或 PEACH_TOKEN 指定时,配置页不能更换。
  • 读取顺序是 --token 参数、PEACH_TOKEN 环境变量、口令文件。不要长期用 --token <口令> 传递,同一台电脑上的其他程序能从进程列表看到命令行。口令也不写进 config.toml,因为那份文件可能会被贴进 issue。
  • 脚本用 X-Token 请求头携带口令。?t=<口令> 查询参数也能用,但口令会留在访问日志、代理日志和浏览历史里,只在一次性场合用。
  • peach serve 监听非回环地址却没有口令时,会直接拒绝启动,而不是只打印警告:托盘在后台启动服务,警告没人看得见,服务却已经对整个局域网开放了。只监听 127.0.0.1 时可以没有口令。
  • 开启两台电脑之间的复制时,两台要用同一份口令文件,复制过去即可。

口令与密码的比对都用常量时间比较。

网络暴露

  • peach serve 默认只监听 127.0.0.1,地址和端口在 <Peach 数据目录>/config.toml 的 [server] 段。只有把 host 改成 0.0.0.0 或某个局域网地址,同一网段的设备才能访问。独立测试包在首次设置里选「同一局域网的设备」时监听 0.0.0.0。
  • 源码部署使用 HTTPS,证书由本机自签的 CA 签发,不用公开 CA。peach init 在 <Peach 数据目录>/secrets/tls/ 生成 CA 与服务器证书。服务器证书有效期 397 天(Apple 对 TLS 服务器证书的上限是 398 天);本机地址变化时 Peach 用同一个 CA 重新签发,已经信任过这个 CA 的设备不用重装。
  • 需要访问的设备只安装并信任 peach-local-ca.crt,任何私钥都不外发。配置页下载的只有重新编码的公开证书。手机扫码下载的地址带 10 分钟有效的签名,只能换到这张公开证书,Peach 重启后作废。安装与指纹核对方法见 运行与配置。
  • Windows 独立测试包在局域网里使用 HTTP,传输不加密。
  • 不要用端口转发或反向代理把 Peach 直接放到公网。 Peach 没有审计日志,也没有第二道认证,这样做等于把整个馆藏和所有修改权限交出去。
  • 配置页的「Cloudflare 公网入口」必须先设访问密码才能启动,只适合临时预览。长期从外网访问,请用 VPN 一类的私有通道。
  • 每个响应都要求搜索引擎不收录(X-Robots-Tag: noindex,/robots.txt 禁止抓取),这一项不能关闭。

凭据与数据

  • 站点 Cookie、令牌、访问密码和 TLS 私钥都放在 <Peach 数据目录>/secrets/,不进 Git、不写日志、不出现在任何 API 返回里。备份数据目录就等于备份了这些凭据,请按保管凭据的标准存放备份。
  • 数据库 <Peach 数据目录>/database/ledger.db 记录了文件路径、演员等资料和观看记录。它和媒体一样不属于代码仓库。提交 issue、日志或截图之前,先去掉路径、局域网地址和账号名。

报告漏洞

请用本仓库 GitHub Security 标签页里的 Private vulnerability reporting 提交,不要开公开 issue。

报告里请写清受影响的版本或提交、复现步骤和实际影响。仓库由一个人维护,响应尽力而为,修复顺序按实际影响排。