seaweedfs 常用命令

SeaweedFS (通常简称为 weed) 的集群管理和维护主要通过 weed shell 来完成。

命令

为了方便自动化运维，SeaweedFS 允许你通过交互式 shell 运行命令，也可以直接在命令行通过 -e 参数单条执行。

以下是你提到的常用核心操作命令总结，假设 Master 节点地址是 127.0.0.1:9333

非交互式直接执行的方式，格式为：

    
    bash
  
weed shell -master=<master_ip:port> -e '<command>'

交互式

bash

$ weed shell
> 输入相关的命令

volume

物理层命令：`weed volume` (定义物理存储空间)

weed volume 是启动 Volume Server 节点的命令。但在启动时，你通过 -dir 和 -max 参数，定义了该机器上能够创建的最大 Volume 数量和物理存放位置。这是所有逻辑 Volume 存在的前提。

常用参数解析：

-dir：数据存储路径，可以指定多个。
-max：每个路径允许创建的 Volume 上限个数（默认通常是 7 或 8，一个 Volume 默认最大 30GB）。

示例（在 Volume 节点机器上运行）：

    
    bash
  
# 示例：启动 Volume 节点，配置两块盘，每块盘最多允许创建 50 个 Volume
weed volume -mserver=127.0.0.1:9333 -port=8080 -dir=/mnt/disk1,/mnt/disk2 -max=50,50

(注：执行此命令后，节点加入集群，Master 就可以向这些 /mnt/disk 目录中分配真实的 .dat 和 .idx Volume 数据文件了)

volume.list (查看集群状态)

    
    bash
  
# 列出所有 Volume 的分布情况
volume.list

volume.mark (标记 Volume 状态)

作用：将指定的 Volume 标记为只读 (readonly) 或取消只读。常用于保护某个 Volume 不再被写入新的数据，或者配合迁移、备份操作。

示例：

    
    bash
  
# 将节点 192.168.1.10:8080 上的 volume 5 标记为只读
volume.mark -node=192.168.1.10:8080 -volumeId=5 -readonly

# 取消只读状态，恢复可写
volume.mark -node=192.168.1.10:8080 -volumeId=5 -readonly=false

volume.grow (预分配/强制扩容 Volume)

volume.grow 是在集群中主动创建逻辑 Volume 的标准命令。你可以通过指定参数，精确控制新建 Volume 的归属和备份策略。

作用：手动在集群中预先创建指定数量的 Volume。通常 SeaweedFS 是按需自动创建 Volume 的，但在进行容量规划、或者想强制在特定的数据中心 (dataCenter) / 机架 (rack) 分配空间时，这个命令非常有用。

常用参数解析：

-count：要创建的 Volume 数量（默认 1）。
-replication：副本策略（如 000 无副本，001 同机架备份 1 份，010 同数据中心不同机架备份 1 份）。
-collection：指定 Volume 所属的集合名称（用来做业务数据隔离）。
-dataCenter / -rack：指定在哪个数据中心或机架创建。

示例：

    
    bash
  
# 示例 1：创建一个普通的 Volume，不指定其他参数
volume.grow

# 示例 2：为图片业务单独创建 5 个 Volume，放到集合 'images' 中
volume.grow -collection=images -count=5

# 示例 3：在 dc1 数据中心创建 3 个 Volume，并设置跨机架双副本 (010)
volume.grow -dataCenter=dc1 -replication=010 -count=3

# 示例 4：为特定集合指定副本策略并创建
volume.grow -collection=videos -replication=001 -count=10

volume.move (移动 Volume)

作用：将一个 Volume 从一个 Volume Server (节点) 移动到另一个节点。常用于手动负载均衡、磁盘空间调整或节点硬件更换前的准备。

示例：

    
    bash
  
# 将 volume 12 从 10 节点移动到 11 节点
volume.move -source=192.168.1.10:8080 -target=192.168.1.11:8080 -volumeId=12

volumeServer.evacuate (清空/疏散节点数据)

作用：极其重要的运维命令。当你需要下线一台 Volume Server（比如机器报废、重装系统、退役）时，该命令会自动将该节点上的所有 Volume 安全地迁移到集群中的其他节点。

示例：

    
    bash
  
# 疏散 192.168.1.10:8080 上的所有数据到其他空闲节点
volumeServer.evacuate -node=192.168.1.10:8080

注：这是一个耗时操作，具体时间取决于节点上的数据量。如果中断，可以再次运行，它会继续迁移剩余部分。

volumeServer.leave (节点离线)

作用：通知 Master 某个 Volume Server 即将离开集群，将其标记为不可用，阻止新的写入请求路由到该节点。注意：它不会移动数据，通常配合 evacuate 或在彻底废弃且数据已不重要时使用。

示例：

    
    bash
  
# 让节点 192.168.1.10:8080 优雅离线
volumeServer.leave -node=192.168.1.10:8080

volume.balance (自动负载均衡)

如果不手动 volume.move，可以利用自动均衡命令让集群自己将拥挤节点的数据挪到空闲节点。

    
    bash
  
# 强制执行全局卷的负载均衡
volume.balance -force

volume.fix.replication (修复副本缺失)

极其重要：如果一台机器意外宕机且无法恢复（没来得及执行 evacuate），集群中配置了副本（如 001, 010）的 Volume 会处于“副本缺失”状态。此命令会扫描并重新复制补充缺失的副本。

    
    bash
  
# 扫描集群并自动修复缺失的副本数据
volume.fix.replication

cluster

cluster.status

在进行 move 或 evacuate 之前，必须先看一眼集群现状。

    
    bash
  
# 查看集群节点和拓扑状态
cluster.status

在 SeaweedFS 中，Volume（卷）的创建通常是自动触发的。当上传文件时，如果现有的 Volume 满了，或者没有符合你指定条件（如 collection 集合名、replication 副本策略）的 Volume，Master 节点会自动分配并创建新的 Volume。

但在实际生产环境中，为了预留空间、控制资源池或进行容量规划，经常需要手动预创建 Volume。

S3 兼容模式

s3.bucket

很多时候 SeaweedFS 是为了代替 MinIO 或 AWS S3。在这种架构下，我们通常不直接管理 Volume，而是创建 Bucket（系统底层会自动把 Bucket 映射为 collection，并自动去 grow volume）。

示例：

    
    bash
  
# 通过 weed shell 创建一个 S3 Bucket
s3.bucket.create -name=my-app-bucket

# 查看当前已有的 S3 Buckets
s3.bucket.list

access_key/secret_key 配置

在 SeaweedFS 中配置 S3 的 access_key (AK) 和 secret_key (SK) 与常见的通过命令行参数直接传递不同。

SeaweedFS 的 S3 网关（weed s3）默认是**匿名访问（不需要验证）**的。要启用鉴权，必须通过一个 JSON 配置文件（通常命名为 s3.json）来定义用户、密钥和权限。

第一步：创建 s3.json 配置文件

在运行 weed s3 网关的机器上，新建一个 s3.json 文件。SeaweedFS 支持多用户、多密钥以及细粒度的权限控制（如只读、读写、管理员）。

s3.json 完整示例：

    
      
      
    
    json
  
{
  "identities": [
    {
      "name": "admin_user",
      "credentials": [
        {
          "accessKey": "admin_ak",
          "secretKey": "admin_sk"
        }
      ],
      "actions": [
        "Admin",
        "Read",
        "Write",
        "List",
        "Tagging"
      ]
    },
    {
      "name": "readonly_user",
      "credentials": [
        {
          "accessKey": "guest_ak",
          "secretKey": "guest_sk"
        }
      ],
      "actions": [
        "Read",
        "List"
      ]
    }
  ]
}

权限（actions）说明：

Admin: 允许创建/删除 Bucket 等高危操作。
Read: 允许下载对象 (GetObject)。
Write: 允许上传对象 (PutObject)。
List: 允许列出 Bucket 内容 (ListObjects)。
Tagging: 允许修改标签。
第二步：带上配置启动 S3 网关

启动 S3 网关时，使用 -config 参数指定刚才创建的 s3.json 路径。

示例（假设 Filer 运行在本地）：

    
    bash
  
weed s3 -filer=127.0.0.1:8888 -port=8333 -config=/path/to/s3.json

💡 提示：一旦加上了 -config，匿名访问就会被拒绝，所有请求都必须携带合法的 AK/SK。

第三步：热更新配置（无需重启服务）

在生产环境中，如果你想新增一个用户或修改密钥，不需要重启 S3 服务。SeaweedFS 提供了两种动态更新的方法：

方法 A：直接修改文件

SeaweedFS S3 会在后台自动监控这个 s3.json 文件。你只需要用 vim 编辑该文件并保存，S3 网关会在几秒钟内自动热重载配置。

方法 B：通过 weed shell 将配置托管到集群（推荐分布式架构使用）

如果集群有多台 S3 网关，一个个改文件很麻烦。可以把 s3.json 上传到 Filer 的内部配置目录 /etc/weed/s3.json，所有的 S3 网关都会自动从这里读取。

示例（将本地配置推送到集群）：

    
    bash
  
# 将刚刚写好的 s3.json 复制到 filer 的全局配置目录
weed filer.copy /path/to/local/s3.json http://127.0.0.1:8888/etc/weed/s3.json

# (可选) 通过 shell 确认配置是否已经成功写入集群
s3.configure -read

s3 接口测试

可以使用官方的 aws-cli 命令行工具来测试你的 SeaweedFS S3 接口。

1. 配置 AWS CLI 环境变量：

    
    bash
  
export AWS_ACCESS_KEY_ID="admin_ak"
export AWS_SECRET_ACCESS_KEY="admin_sk"

2. 测试创建 Bucket：

    
    bash
  
# 注意：必须要加 --endpoint-url 指向 seaweedfs S3 端口
aws --endpoint-url http://127.0.0.1:8333 s3 mb s3://test-bucket

3. 测试上传文件：

bash

aws --endpoint-url http://127.0.0.1:8333 s3 cp /etc/hosts s3://test-bucket/

4. 权限拦截测试： 如果你换成配置中 readonly_user 的 guest_ak 和 guest_sk 再次执行上传，系统将会返回 AccessDenied 错误，说明权限管控已成功生效。

s3.configure

s3.configure 是 SeaweedFS weed shell 中用于动态管理 S3 用户、访问密钥（AK/SK）和权限的核心命令。

相比于手动编写 s3.json 文件再上传，使用 s3.configure 更加安全且方便。它会将配置直接写入 Filer 集群内的全局配置目录（/etc/weed/s3.json），并且所有 S3 网关节点会自动热重载，无需重启服务。

以下是 s3.configure 常用操作的总结及可直接执行的示例（假设 Master 是 127.0.0.1:9333）：

查看当前 S3 配置 (-read)

作用：读取并打印出集群当前存储的完整 S3 身份认证信息。

示例：

bash

s3.configure -read

(输出结果将是一个完整的 JSON 字符串，显示当前所有的 users、credentials 和 actions)

添加/更新用户及其 AK/SK

作用：创建一个新用户（如果用户已存在则覆盖更新其密钥），并赋予指定的权限。 常用权限 (actions)：Admin (管理/建桶), Read (下载), Write (上传), List (列出对象), Tagging (打标签)。多个权限用英文逗号隔开。

示例：

场景 A：创建一个全权限管理员账户

    
    bash
  
s3.configure -user=admin -access_key=admin_ak -secret_key=admin_sk -actions=Admin,Read,Write,List,Tagging -apply

场景 B：创建一个只能上传和下载的普通应用账号（不能建桶/删桶）

    
    bash
  
s3.configure -user=app_user -access_key=app_ak -secret_key=app_sk -actions=Read,Write,List -apply

场景 C：创建一个纯只读的访客账号

    
    bash
  
s3.configure -user=guest -access_key=guest_ak -secret_key=guest_sk -actions=Read,List -apply

删除 S3 用户 (-delete_user)

作用：吊销某个用户的访问权限，将其从配置中移除。

示例：

    
    bash
  
# 删除刚才创建的访客账号
s3.configure -delete_user=guest -apply

关键避坑与最佳实践

不要与本地 -config 混用：如果你决定使用 s3.configure 命令来管理集群密钥，那么在启动 weed s3 网关服务时，不要加 -config=/path/to/local/s3.json 参数。只需像这样正常启动即可：
bash
weed s3 -filer=127.0.0.1:8888 -port=8333
它会自动从 Filer 内部路径（/etc/weed/s3.json）读取你用 s3.configure 配置好的密钥，并开启鉴权拦截。
配置生效时间：执行完 s3.configure 写入新配置后，底层的 S3 服务通常会在 3 ~ 5 秒内自动感应到 Filer 文件的变化并刷新内存中的验证规则，你无需重启任何进程，直接用新密钥测试即可。

最佳运维实践

节点安全下线流程

如果你要安全下线一台正在运行的机器（例如 192.168.1.10），标准流程应为：

weed shell -e 'volumeServer.evacuate -node=192.168.1.10:8080' (把数据全搬走)
weed shell -e 'volumeServer.leave -node=192.168.1.10:8080' (通知集群它要走了)
在 192.168.1.10 机器上 kill 掉 weed volume 进程。

命令

volume

物理层命令：weed volume (定义物理存储空间)

volume.list (查看集群状态)

volume.mark (标记 Volume 状态)

volume.grow (预分配/强制扩容 Volume)

volume.move (移动 Volume)

volumeServer.evacuate (清空/疏散节点数据)

volumeServer.leave (节点离线)

volume.balance (自动负载均衡)

volume.fix.replication (修复副本缺失)

cluster

cluster.status

S3 兼容模式

s3.bucket

access_key/secret_key 配置

s3 接口测试

s3.configure

关键避坑与最佳实践

最佳运维实践

节点安全下线流程

物理层命令：`weed volume` (定义物理存储空间)