简体中文

English

简体中文

English

主题

远程节点存储策略教程 ​

这一篇覆盖什么

这一篇讲怎么把已经接入的从节点作为存储策略后端使用：创建接收落点、创建 remote 存储策略、配置策略组规则、绑定用户或团队，并验收真实上传下载。

如果你还没有把从节点接入主控，先看 远程节点。
如果你用 Docker 跑从节点，先看 Docker 部署从节点。

适合什么时候用 ​

远程节点适合这些场景：

  • 主控节点负责登录、后台、分享和 WebDAV，真实对象写到另一台机器
  • 家里 / 办公室 / 机房有额外存储机器
  • 想把大文件或特定团队的文件分流到独立节点
  • 想让某个从节点再写入它本地磁盘或它能访问的 S3 / MinIO

它不是多主集群，也不是自动故障切换。主控仍然是唯一控制面。

当前版本需要主控能访问从节点

当前远程节点存储策略仍然要求主控节点可以主动访问从节点的 base_url。

如果从节点在 NAT、CGNAT 或纯内网后方，只能主动访问主控，而主控无法回连从节点，enroll 可能仍然能完成，但后续的能力探测、接收落点同步和对象读写都会失败。

这类“只出不进”的从节点接入需要反向连接通道，已经在 issue #136 跟进。在该能力落地前，请先通过公网域名、内网互通、VPN、WireGuard、frp 或反向代理，让主控可以访问从节点。

先分清三层 ​

text
远程节点记录
  |
  +-- 接收落点
      |
      +-- remote 存储策略
          |
          +-- 策略组规则
              |
              +-- 用户或团队绑定策略组

每一层负责的事不同：

层级负责什么入口
远程节点记录主控知道有哪台从节点，怎么访问它管理 -> 远程节点
接收落点从节点收到对象后写到本地还是 S3管理 -> 远程节点 -> 节点详情
remote 存储策略上传时选择哪台远程节点管理 -> 存储策略
策略组哪些用户/团队/文件大小命中这条策略管理 -> 策略组

当前主控和 follower 之间使用内部远程存储协议 v2。创建 remote 策略和切换策略组前，先让主控测试一次节点连接；测试结果里会带协议版本、服务端版本和能力摘要。

1. 先确认从节点已经 ready ​

在主控后台进入：

text
管理 -> 远程节点

确认目标节点满足：

  • 已完成 enroll
  • 已启用
  • base_url 是主控能访问到的地址
  • 当前网络不是“从节点只能出站、主控无法回连”的场景
  • 点击“测试连接”通过
  • 能力摘要里的内部协议版本兼容当前主控，当前要求 v2
  • /health/ready 返回正常

如果 base_url 为空，可以先完成 enroll，但不能真正承接远程存储流量。生产前必须填上主控能访问到的 HTTP(S) 地址。

2. 创建默认接收落点 ​

打开目标远程节点详情，找到：

text
主控指定的接收落点

第一次建议创建 local 接收落点。

示例：

字段建议
名称default-local
驱动local
基础路径default
默认接收落点开启

local 接收落点的基础路径只能填相对路径。
最终会落在从节点自己的：

text
server.follower.managed_ingress_local_root

下面。例如从节点配置是：

toml
[server.follower]
managed_ingress_local_root = "/data/managed-ingress"

接收落点基础路径是：

text
default

最终对象会写到：

text
/data/managed-ingress/default

没有默认接收落点，remote 策略不能真正写入

enroll 成功只代表主从身份绑定成功。真正接收对象前，从节点还需要一个已应用的默认接收落点。

3. 接收落点选 local 还是 s3 ​

接收落点适合场景注意事项
local从节点本地磁盘、NAS 挂载目录基础路径只能是相对路径，并被限制在 follower 接收根目录下
s3从节点所在网络能访问的对象存储凭证和 endpoint 存在从节点接收落点配置里

第一次接入建议先用 local，把主控到从节点的链路跑通。
确认稳定后，再按需要把从节点接收落点切到 s3。

4. 创建 remote 存储策略 ​

进入：

text
管理 -> 存储策略 -> 新建策略

选择驱动类型：

text
remote

填写：

字段建议
名称Remote Follower A 这类能识别节点的名字
远程节点选择刚才接入并测试通过的节点
单文件大小上限先按测试场景设置，0 表示不限制
分片大小初次保持默认
上传方式初次建议 relay_stream
下载方式初次建议 relay_stream

创建后先保存，并做连接测试。

5. 上传和下载方式怎么选 ​

初次建议：relay_stream ​

上传链路：

text
浏览器 -> 主控节点 -> 从节点 -> 接收落点

下载链路：

text
接收落点 -> 从节点 -> 主控节点 -> 浏览器

优点：

  • 浏览器只需要访问主控节点
  • 排查路径清楚
  • 对从节点公网暴露要求更低

代价：

  • 主控节点仍然承接上传和下载带宽

进阶：presigned ​

上传或下载时，浏览器会直接访问从节点生成的短时效地址。

适合：

  • 想降低主控节点带宽压力
  • 浏览器能稳定访问从节点 base_url
  • 反向代理已经正确暴露从节点

使用前确认：

  • 从节点 base_url 对浏览器可达
  • HTTPS 证书可信
  • 反向代理不会拦截上传/下载路径和必要响应头
  • 从节点接收落点已经应用成功
  • 主控测试连接显示 follower 支持 browser_presigned_cors

如果主控能访问从节点，但用户浏览器访问不到从节点，就不要用远程 presigned。

远程 presigned 的浏览器 CORS 要求比普通主控中继更严格：

方向需要允许的请求头需要暴露的响应头
上传 PUTcontent-typeETag
下载 GET / RangerangeAccept-Ranges、Content-Range、Content-Length

follower 默认的内部协议能力会声明 content-type, range，并暴露 GET 所需的 Accept-Ranges、Cache-Control、Content-Disposition、Content-Length、Content-Range、Content-Type、ETag，以及 PUT 所需的 ETag。如果前面有 nginx、Caddy、Traefik 或 CDN，确认它们没有丢这些响应头。

6. 创建测试策略组 ​

不要直接改默认策略组。先创建一个测试策略组：

text
管理 -> 策略组 -> 新建策略组

示例：

text
Remote Test Group

添加规则：

字段建议
存储策略刚创建的 remote 策略
优先级保持默认或设为最先命中
文件大小范围初次覆盖所有大小

7. 绑定测试用户或团队 ​

绑定用户 ​

进入：

text
管理 -> 用户 -> 用户详情

把测试用户的策略组改成 Remote Test Group。

绑定团队 ​

进入：

text
管理 -> 团队 -> 团队详情

把测试团队的策略组改成 Remote Test Group。

团队空间上传时命中团队策略组，不使用个人用户策略组。

8. 做真实验收 ​

用测试用户登录，按顺序验证：

  1. 上传一个小文件
  2. 上传一个大文件
  3. 下载文件
  4. 创建分享链接并访问
  5. 删除文件，再从回收站恢复
  6. 如果启用了预览，打开一次图片或 PDF
  7. 到从节点检查接收落点目录或对象存储里是否出现对象
  8. 回主控 管理 -> 远程节点 再测一次连接，确认协议版本和能力摘要仍然正常

如果这些都通过，再考虑把真实用户或团队切到远程策略组。

9. 按大小分流到远程节点 ​

常见做法：

text
小文件 -> 主控本地或 S3
大文件 -> 远程节点

在策略组里配置多条规则，例如：

规则文件大小范围存储策略
小文件0 到 100 MiB本地策略
大文件100 MiB 以上remote 策略

保存后分别上传小文件和大文件，确认命中的存储策略符合预期。

10. 切换真实用户或团队 ​

确认测试可用后，再选择切换方式：

场景做法
只让少数用户走从节点到 管理 -> 用户 逐个绑定策略组
让某个团队走从节点到 管理 -> 团队 绑定策略组
新用户默认走从节点把远程策略组设为新用户默认策略组
逐步迁移分批调整绑定，观察任务、日志和远程节点健康状态

切换策略组只影响后续上传。旧文件仍按原来的存储策略读取。

11. 日常维护 ​

定期检查：

  • 主控到从节点的测试连接是否成功
  • 从节点 /health/ready 是否正常
  • 默认接收落点是否仍然已应用
  • 从节点接收根目录磁盘是否充足
  • 从节点如果再写 S3，S3 凭证是否仍然有效
  • 远程策略组是否仍然启用
  • 最近是否有远程上传/下载相关错误

从节点本地接收目录属于正式数据，必须纳入备份策略。
如果接收落点是 S3，也要按对象存储的备份和版本化策略处理。

12. 常见故障 ​

主控测试连接失败 ​

优先检查：

  • base_url 是否是主控能访问到的地址
  • 从节点服务是否正在运行
  • 从节点是否监听外部可达地址
  • 反向代理或防火墙是否放行
  • /health/ready 是否返回正常
  • follower 返回的内部协议版本是否兼容当前主控；当前主控要求 v2

remote 策略上传失败 ​

按顺序查：

  1. 远程节点是否启用
  2. 是否完成 enroll
  3. 是否有已应用的默认接收落点
  4. 从节点接收根目录是否可写
  5. 策略组规则是否真的命中 remote 策略
  6. 用户或团队配额是否已满
  7. 主控和从节点日志里是否有对应错误

presigned 模式失败，但 relay_stream 正常 ​

这通常说明主控到从节点没问题，但浏览器到从节点有问题。

检查：

  • 浏览器能否访问从节点 base_url
  • HTTPS 证书是否可信
  • 反向代理是否转发上传/下载路径
  • CORS 是否允许 content-type / range
  • 响应是否暴露 ETag、Accept-Ranges、Content-Range、Content-Length
  • 公司网络或浏览器是否拦截从节点域名

已有文件突然找不到 ​

优先确认最近是否改过：

  • remote 策略绑定的远程节点
  • 从节点接收落点
  • managed_ingress_local_root
  • 从节点本地目录
  • 从节点接收落点的 S3 endpoint / bucket / prefix

这些字段都决定旧对象在哪里。不要直接改正在使用的真实落点。

基于 MIT 许可证发布

Copyright © 2026 AptS:1547