Sign inSign up

lovechen/synchub

By lovechen

•Updated 6 months ago

Hardened file sync hub with configurable dot-file visibility

Image
0

2.1K

lovechen/synchub repository overview

⁠SyncHub

安全文件分发服务器 — 基于 Token 子串匹配的零信息泄露访问控制。

Docker Pulls

⁠功能特点

  • Token 认证 — 全量扫描所有 HTTP Header key+value，子串匹配 token
  • 零信息泄露 — 非法请求无 HTTP 状态码返回
  • 6 种访问模式 — 黑白名单 × 文件/目录/不过滤
  • 配置热重载 — 修改 config.yml 无需重启
  • SHA256 哈希 — ModTime 缓存 + 路径级剪枝
  • 递归目录 — 子目录文件自动递归列出，per-segment URL 编码
  • JSON API — 支持 Accept: application/json 获取结构化文件列表
  • 双架构 — linux/amd64 + linux/arm64
  • 极小镜像 — scratch 基底，单二进制 (~15MB)

⁠快速部署

# docker-compose.yml
services:
  synchub:
    image: lovechen/synchub
    container_name: synchub
    restart: always
    volumes:
      - ./conf:/app/conf       # 配置文件
      - /data/certs:/app/certs # 文件目录（可多个）

⁠配置说明

配置文件路径: ./conf/config.yml，支持热重载（修改后自动生效，无需重启）。

⁠字段定义
字段类型必填说明
accessPathstring✅URL 路径标识，建议 UUID，首次启动自动生成
tokenstring✅认证令牌，留空 "" 表示公开访问（仅需 accessPath）
modestring✅访问模式，详见下方模式表（末尾加 h 显示隐藏文件）
pathstring✅本地文件系统路径，支持相对路径和绝对路径，目录不存在会自动创建
filters[]string✅过滤关键词列表，"*" 表示匹配所有文件
⁠过滤器行为
  • 白名单模式 (w*)：仅当文件名包含任一 filter 关键词时，才可访问
  • 黑名单模式 (b*)：当文件名包含任一 filter 关键词时，该文件被排除
  • "*" 是通配符，白名单下匹配所有文件，黑名单下排除所有文件（即无文件可访问）
  • filter 匹配的是文件名子串，如 "example.com" 会匹配 example.com.crt、example.com.key 等
⁠完整示例
# 最常用 — 仅文件下载，不列目录
- accessPath: "13241c32-f6ac-11ee-9c56-fb1177d582b9"
  token: "b67b2c20-f6ae-11ee-8cb0-eb61785b0f22"
  mode: wf
  path: ./certs
  filters:
    - "*"

# 带目录列表 — 浏览器可查看文件列表
- accessPath: "8b5dfdf3-92dc-4d33-aef4-3d557eb7f9dc"
  token: "82f1b0d3-a363-40a9-a625-b10573dccba0"
  mode: wa
  path: ./certs
  filters:
    - "*"

# 权限隔离 — 同路径不同 Token 控制可见范围
- accessPath: "13241c32-f6ac-11ee-9c56-fb1177d582b9"
  token: "53030a06-2cc2-47f3-8abe-e124a156559a"
  mode: wf
  path: ./certs
  filters:
    - "example.com"
    - "mysite.org"

# 公开访问 — 无需 Token
- accessPath: "62031d94-da4a-11ef-b333-8ffc0ed740dd"
  token: ""
  mode: wa
  path: ./certs
  filters:
    - "example.com"

# 显示隐藏文件 — mode 末尾加 h
- accessPath: "9a4b2c31-f6ac-11ee-9c56-fb1177d582b9"
  token: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  mode: wah
  path: ./dotfiles
  filters:
    - "*"

多入口机制：同一 accessPath 可配置多条规则（不同 token），服务端按 token 匹配到的第一条生效。不同 accessPath 完全隔离。

⁠认证机制
方式说明
自定义 Headercurl -H "X-Token: {token}" http://host/{accessPath}/
Bearer Tokencurl -H "Authorization: Bearer {token}" http://host/{accessPath}/
任意 Header服务端扫描所有 Header key+value，子串匹配即通过
公开模式token: "" 时仅需正确的 accessPath
⁠访问模式 (mode)

默认隐藏 . 开头的文件/目录，末尾加 h 后缀可显示（如 wfh wah）。

模式名单目录列表文件访问隐藏文件
wf白名单❌✅ 仅匹配 filter隐藏
wa白名单✅✅ 仅匹配 filter隐藏
wd白名单✅ 不过滤✅ 仅匹配 filter隐藏
bf黑名单❌✅ 排除匹配 filter隐藏
ba黑名单✅✅ 排除匹配 filter隐藏
bd黑名单✅ 不过滤✅ 排除匹配 filter隐藏
wfh wah wdh bfh bah bdh同上同上同上显示
⁠API
# HTML 文件列表
curl -H "X-Token: {token}" http://host/{accessPath}/

# JSON 文件列表
curl -H "X-Token: {token}" -H "Accept: application/json" http://host/{accessPath}/

# 下载文件
curl -H "X-Token: {token}" http://host/{accessPath}/subdir/file.txt

JSON 响应格式：

[
  {"name": "file.txt", "hash": "sha256...", "mod_time": "2026-04-09T...", "size": 1234},
  {"name": "subdir/nested.txt", "hash": "sha256...", "mod_time": "...", "size": 567}
]

⁠安全设计

层级措施
路由UUID AccessPath，不可枚举
认证Token 子串匹配，全量 Header 扫描
非法请求静默断开，零信息泄露
路径安全路径规范化 + 前缀校验，防穿越
容器scratch 基底，无 shell

⁠NGINX 参考配置

server {
    listen 443 ssl http2;
    server_name synchub.example.com;

    ssl_certificate     /etc/nginx/ssl/synchub.crt;
    ssl_certificate_key /etc/nginx/ssl/synchub.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    access_log off;
    error_log /dev/null;
}

⁠搭配 SyncNode

SyncNode 是配套的边缘同步客户端，自动从 SyncHub 增量同步文件：

docker pull lovechen/syncnode

详见 lovechen/syncnode⁠。

Tag summary

Content type

Image

Digest

sha256:457499c5c…

Size

15.7 MB

Last updated

6 months ago

docker pull lovechen/synchub