Peergos 1.41.0 常用 CLI 命令与工具详解

Peergos 1.41.0 CLI 全解：22 个子命令与 shell 交互命令逐一实测（注册/文件操作/好友分享/配额管理/用量统计/存储统计/WebDAV 桥），注册口令、配额即时生效等注意事项与排障实录。

PeergosPeergosJavaP2P加密文件传输自托管2026/10/31

Peergos 1.41.0 常用 CLI 命令与工具详解

目标：系统讲清 Peergos 1.41.0 命令行工具的全部子命令（daemon/shell/quota/usage/admin/server-msg/release/sync/webdav/fuse 等）与 shell 交互命令，每条命令配真实输入与回显。全部回显在 Ubuntu 22.04 + Peergos 1.41.0 自托管服务端实测取得。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Peergos 版本：1.41.0（version 子命令实测回显 Version: 1.41.0-web-ui/f5488655ac100ef6f0bc2e95340ee38c0d096b50）
  • 运行形态：服务端常驻运行（部署见《Peergos 1.41.0 Docker Compose 部署指南》），CLI 与服务端同机
  • 安装布局：可执行文件 /opt/peergos/server/Peergos.jar，数据目录 /opt/peergos/data（PEERGOS_PATH=/opt/peergos/data）
  • 测试账号：demoadmin / demofriend（注册由 shell 完成，口令为注册时自动生成的 7 组单词形态强口令）

二、工具概览

Peergos 的所有能力都通过一个 jar（直跑形态）或同布局路径的 Peergos.jar 提供，入口命令为 java -jar Peergos.jar <子命令>。根帮助（-help）实测输出：

java -jar /opt/peergos/server/Peergos.jar -help

Main: Run a Peergos command
Parameters: 
	server-url: Address of the remote Peergos or self-hosted server to use in app/proxy mode
	port: Localhost server port for app/proxy mode
	minimised: Start in the tray with no window (used by the login item)
Sub commands (run -help on a sub command to see more):
	daemon: The user facing Peergos server
	shell: An interactive command-line-interface to a Peergos server.
	sync: Sync a local folder to a Peergos folder
	fuse: Mount a Peergos user's filesystem natively
            Password can be set via an environment variable.
	webdav: Provide a webdav bridge to a Peergos user's filesystem
            Passwords can be set via environment variables.
	quota: Manage quota of users on this server
	usage: Show usage on this server
	server-msg: Send and receive messages to/from users of this server
	server-identity: Manage the identity of this server
	gateway: Serve websites directly from Peergos
	mirror: Commands related to mirroring your data on another server
	release: Commands for downloading Peergos releases
	migrate: Move a Peergos account to this server.
	version: Print the Peergos version
	update-home-server-id: Update the home server id for a user
	identity: Create or verify an identity proof
	proxy: Run a local proxy to a peergos server. 
            This allows you to get the security and caching benefits of localhost, 
            without running a daemon which exposes your IP address. 
	admin: Manage users on this server
	stop: Stop any running Peergos instance
	gc: Garbage collect the blockstore, in the running server if there is one, otherwise in this process
	pki: Start the Peergos PKI Server that has already been bootstrapped
	pki-init: Bootstrap and start the Peergos PKI Server
	ipfs: Configure and start IPFS daemon

按使用频率把 22 个子命令分四档：

档位子命令用途
日常必用daemon、shell服务端本体；文件/分享交互操作
服务器管理quota、usage、admin、server-msg、stop、gc注册令牌、配额、用量统计、用户管理、停服、垃圾回收
客户端接入sync、fuse、webdav、proxy、gateway目录同步、挂载、WebDAV 桥、本地代理、网站托管
高级/运维version、release、migrate、mirror、server-identity、identity、update-home-server-id、pki、pki-init、ipfs版本/升级、账号迁移、数据镜像、身份轮换、PKI 与 IPFS

服务端参数详解（daemon）不在本文展开，见《Peergos 1.41.0 配置参数详解》。

三、前置条件

  1. Java >= 25 已安装（java -version 确认；本文验证机为 openjdk 25.0.5 LTS）。
  2. 有可连的 Peergos 服务端：同机自托管（http://127.0.0.1:8000）或远端（https://你的域名）。本文全部实测基于本机服务端。
  3. 已知数据目录：服务端管理类子命令（quota/usage/admin 等）读写 $PEERGOS_PATH 下的 SQLite 文件，执行前设置环境变量：
export PEERGOS_PATH=/opt/peergos/data
  1. 用户账号与口令：CLI 登录需要 Peergos 用户名 + 口令。注册时口令是自动生成的（见 4.2 注册流程），务必先保存好。

四、各工具详解

4.1 version：查看版本

java -jar /opt/peergos/server/Peergos.jar version

实测回显：

Version: 1.41.0-web-ui/f5488655ac100ef6f0bc2e95340ee38c0d096b50

回显中 1.41.0 为版本号，web-ui/f5488655... 为 web 资源构建标识。

4.2 shell：交互式命令行（文件与分享操作）

登录。推荐非交互参数形式（实测；口令经 -PEERGOS_PASSWORD 传入，避免管道交互）：

java -jar /opt/peergos/server/Peergos.jar shell -peergos-url http://127.0.0.1:8000 -username demoadmin -PEERGOS_PASSWORD 'twist-talent-thunder-flock-dress-clip-hollow'

实测登录过程输出：

Generating keys
Logging in
Retrieving Friends

出现这三行后即进入 REPL 提示符（用户名@服务器地址 >）。官方 README 还记录了纯交互式登录（依次提示输入服务器地址、用户名、密码）与桌面 App 形态，效果相同。可选参数共 4 个（shell -help 实测）：username、PEERGOS_PASSWORD、peergos-url、http_proxy（格式 host:port，走代理连远端服务器时用）。

注册新用户（shell 的特殊用法：用户名不存在时进入注册流程）。实测交互序列：

java -jar /opt/peergos/server/Peergos.jar shell -peergos-url http://127.0.0.1:8129 -username demoadmin

Generated password: twist-talent-thunder-flock-dress-clip-hollow
Re-enter password
 >
Enter a signup token, or press enter if this server doesn't require one.
(An admin of the server can create one with: java -jar Peergos.jar quota token create)
 >

流程：自动生成口令（必须立即抄写）→ 重输一遍 → 粘贴注册令牌（令牌生成见 4.3）→ 密钥初始化 1–2 分钟 → 打印 Available commands: 帮助横幅即注册成功。

help：全部 shell 命令清单（登录后输入 help，实测完整回显）：

Available commands:
help                                                                        	Show this help.
exit                                                                        	Disconnect.
get remote-path <local path>                                                	Download a file, or an entry inside a zip archive.
cat remote-path                                                             	Print the contents of a remote file, or of an entry inside a zip archive.
mkdir dir-name                                                              	Create a directory
put <--skip-existing> local-path <remote-path>                              	Upload a file or folder, into a zip archive if the remote path is in one.
ls <-l> <path>                                                              	List contents of a remote directory, or of a zip archive.
lls <path>                                                                  	List contents of a local directory.
rm remote-path                                                              	Remove a remote file, or an entry in a zip archive.
mv remote-path new-name-or-path                                             	Rename or move a remote file, including inside a zip archive.
space                                                                       	Show used remote space.
get_follow_requests                                                         	Show the users that have sent you a follow request.
process_follow_request pending-follower accept|accept-and-reciprocate|reject	Accept or reject a pending follow-request.
follow user                                                                 	Send a follow-request to another user.
share_read remote-path user                                                 	Grant read access for a file or directory to another user.
share_write remote-path user                                                	Grant write access for a file or directory to another user.
make_public remote-path                                                     	Make a file or directory readable by anyone.
passwd                                                                      	Update your password.
cd <remote-path>                                                            	change (remote) directory, which may be inside a zip archive.
lcd local-path                                                              	change (local) directory.
pwd                                                                         	Print (remote) working directory.
lpwd                                                                        	Print (local) working directory.
quit                                                                        	Disconnect.
bye                                                                         	Disconnect.

Note: <TAB> based autocomplete is available on most commands.

文件操作全流程实测（准备本地测试文件后逐条执行；输出为逐条实测回显）：

pwd
mkdir docs
ls
ls -l
put notes.txt notes.txt
cat notes.txt
get notes.txt out-notes.txt
mv notes.txt docs/notes.txt
ls -l docs
rm docs/notes.txt
space

实测回显：

pwd
Remote working directory: /demoadmin
mkdir docs

Successfully created /demoadmin/docs
ls
docs
ls -l
drw          -  2026-10-31 01:33  docs/
put notes.txt notes.txt

(1/1) /demoadmin/notes.txt/notes.txt                |	[====================]	(1/1) /demoadmin/notes.txt/notes.txt                /	[====================]	
Successfully uploaded /opt/peergos/data/notes.txt to remote /demoadmin/notes.txt
ls -l
drw          -  2026-10-31 01:33  docs/
-rw       23 B  2026-10-31 01:35  notes.txt
cat notes.txt
hello peergos cli test

get notes.txt out-notes.txt

(1/1) /demoadmin/notes.txt                          |	[====================]	
Downloaded /demoadmin/notes.txt to /opt/peergos/data/out-notes.txt
mv notes.txt docs/notes.txt
Moved /demoadmin/notes.txt to /demoadmin/docs/notes.txt
ls -l docs
-rw       23 B  2026-10-31 01:35  notes.txt
rm docs/notes.txt
Deleted /demoadmin/docs/notes.txt
ls docs

space
Total space used: 0 MiB.

要点解读：

  • put 本地路径 远端路径：远端路径省略目录时落到当前远端目录；实测把 /opt/peergos/data/notes.txt 传成 /demoadmin/notes.txt；
  • ls -l 输出列依次为权限形态（drw/rw）、大小、时间、名称，目录带 / 后缀；目录大小列显示 -（端到端加密下服务器不可知聚合大小，space 才是真实用量）；
  • cat/get 可直接读 zip 内条目（help 原文）；mv 兼作重命名与移动；cd/lcd/lpwd 用于远端与本地双工作目录切换；
  • 退出用 exit（或 quit/bye，三者等价，实测 exit 生效后打印 Exiting）。

社交与分享命令实测（两账号场景：demoadmin 与 demofriend）：

demoadmin 侧发起关注并上传测试文件（实测）：

follow demofriend
Sent follow request to 'demofriend'

demofriend 侧处理关注请求（实测）：

get_follow_requests
You have pending follow requests from the following users:
demoadmin
process_follow_request demoadmin accept-and-reciprocate
Processed follow request from 'demoadmin' with accept_and_reciprocate action.

process_follow_request 三个动作：accept（仅接受关注）、accept-and-reciprocate（接受并反向关注，成为双向好友）、reject。

分享与公开（demoadmin 侧，实测含一次失败）：

share_read notes.txt demofriend
File not shared: specified-user demofriend is not following you
make_public notes.txt
Made file '/demoadmin/notes.txt' public.
Anyone can now read it at http://127.0.0.1:8000/public/demoadmin/notes.txt

⚠️ 注意：share_read/share_write 要求对方已关注你（好友关系建立后才可分享），否则报 File not shared: specified-user ... is not following you。make_public 则无需好友关系，回显直接给出公开只读 URL。passwd 可修改口令（旧口令加密的登录数据会随之重加密）。

4.3 quota：配额与注册令牌管理（服务器侧）

quota 子命令直接读写数据目录中的配额库，在服务器上执行（需 PEERGOS_PATH），不连网络、立即生效。子命令：local、home、show、set、requests、token（quota -help 实测）。

token create / token list：注册令牌（实测）：

java -jar /opt/peergos/server/Peergos.jar quota token create -count 1
java -jar /opt/peergos/server/Peergos.jar quota token list

Created signup tokens:
03d8ca4d7b41589bc403ba033e8068e2e225228646fbe525cd51c7c67fd6a2e3

Stored tokens:
d886e6a9d7d38660bc05d51d237ba57d1585a1c670789de2d7612760b4bf1e3c
9ed0d463fc8a22ff5857b2a52840deefb3d9cbd33029cad4b24f99434c8fc8fb
3bfe14ea9e62d48a10381dda860c0746295c5f1ccf6bbeb901a5460d5cd52fb6

-count N 一次生成 N 枚；列表输出的是未使用令牌。

local / show：看有配额的用户与余量（实测）：

quota local
demoadmin
demofriend

quota show
demoadmin 1 GiB
demofriend 1 GiB

set：调整配额（实测：把 demofriend 调到 5g 后核对）：

java -jar /opt/peergos/server/Peergos.jar quota set -username demofriend -quota 5g
java -jar /opt/peergos/server/Peergos.jar quota show -username demofriend

demofriend 5 GiB

配额值支持字节或 k/m/g/t 后缀；set 后立即写库生效，无需重启服务端。quota requests 列出待审批的空间扩容请求（配合 config 的 admin-usernames 在 Web 界面审批）。

4.4 usage：实际用量统计（服务器侧）

java -jar /opt/peergos/server/Peergos.jar usage show

实测回显：

peergos 0 B
demofriend 79673 B
demoadmin 100124 B

不带 -username 列出全部用户；usage show -username demoadmin 看单用户。注意与 quota show 的区别：usage 是已用、quota 是可用上限，做容量规划两者对照看。

4.5 admin：用户与存储管理（服务器侧）

admin 子命令组：bat、storage、mfa、delete、dial（admin -help 实测）。

storage stats：块存储统计（实测）：

java -jar /opt/peergos/server/Peergos.jar admin storage stats

实测回显（日志行 + 统计行）：

Cbor blocks: 8733, raw blocks: 0, cbor size: 2860374, raw size: 0

含义：密文块（CBOR）8733 个共约 2.86MB，原始块 0。storage recalculate 用于用量数据库与实际块数不一致时重算。

其余子命令：admin delete -username <用户> 从本服务器删除用户并回收配额（不可逆，慎用）；admin mfa 列出本地用户的双因子配置；admin dial <peerid> 拨号探测对端节点并核对身份；admin bat generate 生成跨服务器镜像数据用的 BAT。

4.6 server-msg：站内消息（服务器侧）

子命令：show、send、new、new-users、active-users（server-msg -help 实测）。面向「本服务器用户」的运营型消息：

  • server-msg new-users：列出尚未发过欢迎消息的新用户；
  • server-msg send -username <用户> -msg "内容"（或 -msg-file <文件>、-usernames <名单文件> 批量）：发消息；
  • server-msg show -username <用户>：与指定用户的消息往来；server-msg new：最近消息；server-msg active-users：活跃用户清单。

⚠️ 注意：这是服务器管理员对站内用户的明信片式通道，不是端到端加密聊天（用户间私密聊天在客户端内）。

4.7 release：版本查询与升级包下载

java -jar /opt/peergos/server/Peergos.jar release latest-version

实测回显：

1.41.0

release get -type <类型> -dir <目录> 从 Peergos 网络自身下载发行包，-type 实测取值（release get -help 原文）：[jar, flatpak, rpm, msi, pkg, apk]，-version 缺省为最新版，-overwrite 覆盖已有文件。升级流程：下载新版 jar → 停服替换 → 重启（数据目录兼容，配置在 config 中不受影响）。

4.8 sync：本地目录双向同步

参数（sync init / sync dir help 实测）：peergos-url、links（Peergos 目录的可写 secret link，逗号分隔）、local-dirs（本地目录，逗号分隔）、max-parallelism（并行度）、block-cache-size-bytes（本地块缓存大小，如 5g）、run-once（只同步一轮）。

标准流程（官方 README 记载，实测初始化入口）：先 sync init -peergos-url <地址> 交互输入账号与远端目录，得到形如 Run the sync dir command with the following args: -links secret/... -local-dirs /path/to/dir 的参数串，再执行 sync dir -peergos-url <地址> -links <link> -local-dirs <本地目录> 常驻同步。双向同步的启停/删除方向可在客户端同步设置页控制。

4.9 webdav：WebDAV 桥

把某个账号的 Peergos 文件系统以 WebDAV 协议暴露给任意 WebDAV 客户端。参数（webdav -help 实测）：username、PEERGOS_PASSWORD（Peergos 侧口令）、webdav.username、PEERGOS_WEBDAV_PASSWORD（WebDAV 侧自定口令）、webdav.authorization.scheme（basic 或 digest）、webdav.port、peergos-url。

实测启动（Peergos 侧口令用注册时生成的强口令，WebDAV 侧演示口令 q1w2e3r4）：

java -jar /opt/peergos/server/Peergos.jar webdav -peergos-url http://127.0.0.1:8000 -username demoadmin -PEERGOS_PASSWORD 'twist-talent-thunder-flock-dress-clip-hollow' -webdav.username admin -PEERGOS_WEBDAV_PASSWORD 'q1w2e3r4'

实测回显（就绪标志）：

INFO: Using DIGEST authorization
Webdav bridge started and ready to use at localhost:8090

就绪后用任意 WebDAV 客户端挂载 http://127.0.0.1:8090/<用户名>/（官方 README：浏览器访问 http://localhost:8090/$YOUR-USERNAME）。默认认证方案为 DIGEST（实测日志），-webdav.authorization.scheme basic 可切换；桥默认只监听 localhost，供本机客户端使用。

4.10 fuse：原生挂载

fuse: Mount a Peergos user's filesystem natively
Parameters: 
	username: Peergos username
	PEERGOS_PASSWORD: Peergos password
	peergos-url: Peergos service address
	mountPoint: The directory to mount the Peergos filesystem in

（fuse -help 实测原文。）把远端文件系统挂到本地目录 mountPoint，之后用任意本地工具直接读写。前置：Linux 需 FUSE 支持，macOS 装 osxfuse（官方：brew install --cask osxfuse），Windows 装 winfsp（官方：choco install winfsp）。

4.11 proxy：本地安全代理

proxy -help 实测参数：server-url（远端服务器地址）、peergos-url、http_proxy、port（本地端口）、mutable-pointers-cache/account-cache-sql-file/pki-cache-sql-file/bat-cache-sql-file（本地缓存库文件名）、native-tweetnacl-path/native-sqlite-path。用途（help 原文）：在不常驻完整服务端的情况下获得 localhost 的安全与缓存收益，不暴露本机 IP——本地应用连 http://localhost:<port>，由 proxy 经 p2p 转发到远端主服务器。

4.12 其余运维子命令速查

子命令关键参数/子命令用途（help 原文归纳）
daemon见《Peergos 1.41.0 配置参数详解》服务端本体
gatewayport、peergos-url、domain-suffix、public-server、collect-metrics直接从 Peergos 托管网站
migrate-peergos-url、子命令 force把账号迁到本服务器（force 用于原主服务器已失联，需已 mirror + 有配额）
mirror子命令 init（-username、-peergos-url）生成镜像所需的 -mirror.username/-mirror.bat/-login-keypair 三参数
server-identity子命令 gen-next、rotate服务器身份预生成与轮换（防私钥失窃的灾备）
identity子命令 link、verify（-service、-service-username 等）把 Peergos 身份与其他平台账号绑定/验真
update-home-server-id—迁移后修正用户的主服务器指向
gc与 daemon 同参手动触发块存储垃圾回收（有运行中服务端则通知其执行）
stop—停止运行中的 Peergos 实例
pki / pki-init—启动/引导 PKI 服务器（仅自建 PKI 网络用，普通自托管不涉及）
ipfsIPFS_PATH、ipfs-swarm-port、ipfs-swarm-addrs 等单独配置并启动内嵌 IPFS（Nabu）守护进程

五、注意事项

  1. 口令即一切：Peergos 账号完全由用户名 + 口令派生密钥，口令丢失无法找回（官方社交恢复功能需预先设置 N of M 好友）。注册时自动生成的口令必须当场抄写保存。
  2. 两类命令的执行位置不同：shell/sync/fuse/webdav/proxy 是客户端命令（连 -peergos-url）；quota/usage/admin/server-msg/gc/stop 是服务器命令（直接读写 PEERGOS_PATH 下数据，需在服务器上执行）。
  3. 配额类操作即时生效：quota set 直接写 SQLite 配额库并通知运行中的服务端，无需重启（官方 README 原文）。
  4. 敏感命令清单：admin delete（删用户）、server-identity rotate（轮换服务器身份）、quota set（影响用户可用空间）执行前先在测试用户上演练。
  5. JDK 25 运行时会出现 WARNING: A restricted method in java.lang.System has been called 等告警（TweetNaCl/SQLite 原生库 JNI 调用触发），属已知现象，启动命令带 --enable-native-access=ALL-UNNAMED 可消除，不影响功能。

六、常见问题

6.1 注册后不知道密码是什么

注册不设自定义密码：shell 打印 Generated password: <7 组单词>，这就是口令。丢失后只能删除用户重建（admin delete）。

6.2 put 上传的文件去哪了

put 本地路径 远端路径 中远端路径若不含目录，文件落到当前远端工作目录（pwd 查看，注册用户为 /<用户名>）。实测 put notes.txt notes.txt 的回显明确写出 Successfully uploaded /opt/peergos/data/notes.txt to remote /demoadmin/notes.txt。

6.3 share_read 报 File not shared

对方未关注你。先 follow 对方 并等对方 process_follow_request ... accept（或 accept-and-reciprocate）后再 share_read/share_write。实测报错与解决全记录见 4.2 社交命令一节。

6.4 mkdir /docs 在根目录失败

实测回显：

Failed to execute ParsedCommand{cmd=mkdir, line='mkdir /docs', arguments=[/docs]}: Unable to retrieve file at /

根目录 / 是 PKI 域（用户目录的父层），不可写。在自己目录内操作：mkdir docs（实测成功，生成 /demoadmin/docs）。

6.5 管理命令报找不到数据文件

quota/usage/admin 等服务器侧命令按 PEERGOS_PATH 定位 SQLite 文件，未设置时在当前目录找不到。先 export PEERGOS_PATH=/opt/peergos/data 再执行。

6.6 shell 连不上服务端

核对 -peergos-url 必须带协议头（http:// 或 https://，实测漏协议头会连接异常）；同机部署用 http://127.0.0.1:8000；远端服务器明文 http 仅接受私网地址与 localhost（官方 README 网络安全策略），公网请用 https。

七、参考链接

  1. 官方 README（CLI/Shell/Sync/FUSE/Webdav 章节）：https://github.com/Peergos/Peergos#cli
  2. 官方技术手册：https://book.peergos.org/
  3. 姊妹篇：《Peergos 1.41.0 Docker Compose 部署指南》《Peergos 1.41.0 配置参数详解》《Peergos 介绍与选型指南》