Peergos 1.41.0 Docker Compose 部署指南

用 Docker Compose 部署 Peergos 1.41.0：官方镜像选型、compose 编排与 JVM 堆限制验证、注册令牌与首个用户注册实测、数据持久化、等价 docker run 与常用运维命令，排障实录沉淀。

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

Peergos 1.41.0 Docker Compose 部署指南

目标：从零开始在一台 Ubuntu 服务器上用 Docker Compose 部署 Peergos 1.41.0 加密云存储服务端，完成镜像拉取、编排启动、Web 验证、JVM 堆限制验证、注册令牌创建与首个用户注册。全部命令与回显已在 Ubuntu 22.04 实测通过。

一、环境信息

本文部署过程在以下环境实测：

  • 操作系统：Ubuntu 22.04（x86_64）
  • Docker 版本：29.9.2（docker version --format '{{.Server.Version}}' 实测；Compose v2 插件随 Docker Engine 提供）
  • Peergos 版本：1.41.0（官方发行通道 release latest-version 实查返回 1.41.0，查询日期 2026-10-31）
  • 官方镜像：ghcr.io/peergos/web-ui:master（README 自托管章节官方指定镜像，内置 JRE：openjdk 25.0.5 LTS，实测 java -version 回显）
  • 服务监听端口：8000（镜像内），宿主机映射 8129
  • 数据目录：镜像内 /opt/peergos/data，宿主机以 bind mount 挂载到 compose 目录下的 ./data 子目录
  • JVM 堆限制：-Xms256m -Xmx512m（实测 ps -ef 验证，见 4.5 节）
  • 实测数据目录占用：54MiB（初始化 + 两个测试用户之后，du -sh data 实测）

二、镜像选型说明

Peergos 服务端官方只维护一个自托管镜像：ghcr.io/peergos/web-ui:master（官方 README「Usage - self hosting (with docker)」原文：docker pull ghcr.io/peergos/web-ui:master）。选型要点：

  • 镜像内容：一个镜像同时包含服务端 Peergos.jar（位于 /opt/peergos/server/Peergos.jar）、Web 界面资源（webroot）、内置 JRE（openjdk 25.0.5）与 TweetNaCl/SQLite 原生库（/opt/peergos/native-libs/），宿主机无需安装 Java；
  • 版本与 tag：官方该镜像以 master 持续交付（无逐版本 tag），版本以 jar 内部为准——本文实测 java -jar /opt/peergos/server/Peergos.jar version 返回 Version: 1.41.0-web-ui/f5488655ac100ef6f0bc2e95340ee38c0d096b50；如需固定版本，可改用官方 jar 直跑形态（见《Peergos 1.41.0 配置参数详解》第一章的环境布局说明）并自行锁定下载版本；
  • 镜像体积与内置组件：自带入口脚本 /opt/peergos/docker-entrypoint.sh（官方 README 说明：用 docker exec 进已经运行的服务端执行其他命令时需显式点名该入口脚本）。

本文实测拉取（官方源直连可用，未发生降级）：

docker pull ghcr.io/peergos/web-ui:master

Digest: sha256:fae393ac6ad7610439ef1ab42060e578fd4677093a3073a91a9ee4113a13c01b
Status: Downloaded newer image for ghcr.io/peergos/web-ui:master
ghcr.io/peergos/web-ui:master

💡 技术拓展：Peergos 的发行形态不止容器一种——官方 release get 子命令 help 实测列出 6 种发行类型：jar, flatpak, rpm, msi, pkg, apk，覆盖 Linux/macOS/Windows/Android。本文选容器形态（隔离依赖、升级回滚干净）；直跑 jar 形态则要求宿主机 Java >= 25。

三、前置条件

  1. 服务器已安装 Docker Engine 20.10+ 与 Compose v2 插件：
docker version --format '{{.Server.Version}}'

29.9.2
  1. 目标端口空闲。本文预分配宿主机端口 8129（8000 为镜像内固定服务端口），部署前实测确认未被占用：
ss -ltn | grep :8129 || echo "8129 空闲"

8129 空闲
  1. 数据目录已规划（本文 compose 目录下的 data/ 子目录，bind mount 到镜像内 /opt/peergos/data）。
  2. Peergos 是 p2p 服务端：首次启动需要同步全网 PKI 并连接 IPFS 引导节点，要求服务器能访问公网；后续启动同样需要网络与对端通信。

四、部署步骤

4.1 编写 docker-compose.yml

在部署目录创建 docker-compose.yml。两个易错点必须注意：一是 JVM 堆必须显式限制（默认不限制会吃掉大内存，本文按 256–512MB 规范设置）；二是 entrypoint 完整覆盖为 java 启动行（镜像默认入口不带堆参数）：

name: peergos-1.41.0-stack

services:
  server:
    image: ghcr.io/peergos/web-ui:master
    container_name: peergos-1.41.0-server
    restart: unless-stopped
    entrypoint: ["java", "--enable-native-access=ALL-UNNAMED", "-Xms256m", "-Xmx512m", "-jar", "/opt/peergos/server/Peergos.jar"]
    ports:
      - "8129:8000"
    command: daemon -listen-host 0.0.0.0 -generate-token true -quota-upload-limit-seconds 600 -log-to-console true -public-domain 127.0.0.1:8129 -webroot server/webroot --native-tweetnacl-path /opt/peergos/native-libs/libtweetnacl.so --native-sqlite-path /opt/peergos/native-libs/libsqlitejdbc.so
    volumes:
      - ./data:/opt/peergos/data
    networks:
      - peergos-net

networks:
  peergos-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24

逐项说明：

  • name: peergos-1.41.0-stack：Compose 项目名，生成的网络名形如 peergos-1410-stack_peergos-net；
  • entrypoint：--enable-native-access=ALL-UNNAMED 消除 JDK 25 对原生库调用的告警；-Xms256m -Xmx512m 为 JVM 堆上下限（见 4.5 节验证）；
  • command：daemon 是服务端子命令；-generate-token true 启动即生成一个注册令牌；-quota-upload-limit-seconds 600 限制「上传完整配额所需的最短时长」，防止用户瞬间灌满磁盘；-public-domain 为对外访问域名:端口（域名 + TLS 公网形态的写法见第九章）；-webroot server/webroot 指定 Web 资源目录（相对镜像工作目录 /opt/peergos）；两个 --native-*-path 把 TweetNaCl/SQLite 原生库落到可写路径，避免每次启动写临时文件；
  • volumes：数据目录 bind mount，所有用户数据、块存储、SQLite 元数据、配置文件都在这里，务必落盘持久化；
  • networks：显式指定网段，避免与宿主机上其他 Docker 网段冲突。

4.2 启动服务

docker compose up -d

实测回显：

 Network peergos-1410-stack_peergos-net Creating
 Network peergos-1410-stack_peergos-net Created
 Container peergos-1.41.0-server Creating
 Container peergos-1.41.0-server Created
 Container peergos-1.41.0-server Starting
 Container peergos-1.41.0-server Started

4.3 验证服务状态与启动日志

docker compose ps

NAME                    IMAGE                           COMMAND                  SERVICE   CREATED              STATUS          PORTS
peergos-1.41.0-server   ghcr.io/peergos/web-ui:master   "java --enable-nativ…"   server    About a minute ago   Up About a minute   4001/tcp, 0.0.0.0:8129->8000/tcp, [::]:8129->8000/tcp

启动日志（docker logs --tail 20 peergos-1.41.0-server，实测节选）：

INFO: Logging to /opt/peergos/data/peergos.0.log
INFO: Using IPFS dir /opt/peergos/data/.ipfs
INFO: Using identity provided via command arguments
INFO: Initializing ipfs
INFO: Starting Nabu version: 0.9.0, peerid: 12D3KooWErDT8pDRgAxGH4XekfNdHXpPmpyFawUKuGantuhgebhn
INFO: Starting IPFS...
INFO: Node started and listening on [/ip6/::/tcp/4001/p2p/12D3KooWErDT8pDRgAxGH4XekfNdHXpPmpyFawUKuGantuhgebhn, /ip6/::/udp/4001/quic-v1/p2p/12D3KooWErDT8pDRgAxGH4XekfNdHXpPmpyFawUKuGantuhgebhn]
INFO: Bootstrapping IPFS routing table
INFO: Bootstrapping IPFS kademlia
INFO: NAT traversal status: reachability=PRIVATE, NAT type=UNKNOWN, external addresses=[none discovered yet]
INFO: Bootstrap connected to 10 nodes close to us. [12D3KooW9syRZpRZKiJbLrrxbcuymbhT5BTF9hjG6bykH42q29Mb, ...]
INFO: MDNS discovery enabled
INFO: Starting Nabu API server at 127.0.0.1:5001
INFO: Starting local Peergos server at: localhost:8000
INFO: Using webroot from local file system: Optional[server/webroot]
INFO: Caching web-resources

⚠️ 注意：IPFS 引导、Kademlia 路由表 bootstrap 需要约 1 分钟，日志出现 Starting local Peergos server at 之后 HTTP 服务才就绪。首次启动（全新数据目录）会同步全网 PKI，官方文档明示耗时数分钟，期间无 HTTP 服务属正常现象。

4.4 Web 服务可达验证

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/

200

浏览器访问 http://服务器IP:8129/ 即为 Peergos Web 界面登录页。

4.5 JVM 堆限制验证（256–512MB）

Peergos 服务端是 Java 进程，本文通过 compose entrypoint 显式限制堆为 -Xms256m -Xmx512m。验证方法（在宿主机查看 java 进程完整命令行）：

ps -ef | grep [P]eergos

实测回显（命令行中可见堆参数已生效）：

root     2246470 2246445  0 09:15 ?        00:00:30 java --enable-native-access=ALL-UNNAMED -Xms256m -Xmx512m -jar /opt/peergos/server/Peergos.jar daemon -listen-host 0.0.0.0 -generate-token true -quota-upload-limit-seconds 600 -log-to-console true -public-domain 127.0.0.1:8129 -webroot server/webroot --native-tweetnacl-path /opt/peergos/native-libs/libtweetnacl.so --native-sqlite-path /opt/peergos/native-libs/libsqlitejdbc.so

修改堆大小的位置就是 compose 的 entrypoint 行：把 -Xms256m -Xmx512m 改成目标值后 docker compose up -d 重建生效。直跑 jar 形态下 JVM 参数位置与 systemd 托管写法见《Peergos 1.41.0 配置参数详解》第十章。

4.6 创建注册令牌并注册首个用户

Peergos 新用户注册必须持有注册令牌（token）。令牌由服务端管理员生成：

docker exec peergos-1.41.0-server java -jar /opt/peergos/server/Peergos.jar quota token create -count 1

实测回显：

Created signup tokens:
03d8ca4d7b41589bc403ba033e8068e2e225228646fbe525cd51c7c67fd6a2e3

列出未使用令牌用 quota token list（实测回显节选）：

Stored tokens:
d886e6a9d7d38660bc05d51d237ba57d1585a1c670789de2d7612760b4bf1e3c
...

命令行注册首个用户（交互式 shell，实测全程回显；-username 后接新用户名）：

docker exec -it peergos-1.41.0-server 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)
 >

流程说明：

  1. 注册不设密码——Peergos 自动生成强口令（如上 7 组单词形态），立即抄写保存，然后按要求重输一遍；
  2. 粘贴上一步生成的注册令牌后回车，密钥生成与初始化需要 1–2 分钟（加密运算）；
  3. 注册完成的标志是 shell 打印出 Available commands: 帮助横幅并进入 用户名@服务器地址 > 提示符——没有额外的 "success" 提示，这是 Peergos 的设计。

也可走 Web 界面注册：浏览器打开 http://服务器IP:8129/?signup=true&token=<令牌>。

注册后从服务器侧验证用户与配额（默认配额 1 GiB）：

docker exec peergos-1.41.0-server java -jar /opt/peergos/server/Peergos.jar quota show

实测回显：

demoadmin 1 GiB
demofriend 1 GiB

五、数据持久化说明

Peergos 的全部状态都在 bind mount 的 ./data（即镜像内 /opt/peergos/data）中，实测初始化 + 两用户后的目录结构与占用（du -sh data → 54M）：

路径内容
config服务端配置文件（首次启动自动生成，持久化所有启动参数）
.ipfs/内嵌 IPFS（Nabu）块存储与 datastore
blocks/块缓存（blocks/cache/config.json 可调缓存上限）
login.sql / quotas.sql / social.sql / space-usage.sql / transactions.sql 等登录、配额、好友、用量、事务等 SQLite 元数据库
mutable.sql / pki-state.cbor / serverids.sql可变指针、PKI 镜像、服务器身份
peergos.N.log滚动服务日志
gc.token / local-api.token内部令牌（chmod 600，勿外泄）

备份策略：停服（docker compose stop）后整目录 tar 打包即可冷备；热备建议对 data/ 做文件级快照（如 btrfs/lvm snapshot），SQLite 文件热拷贝有撕裂风险。恢复时把备份目录原位放回再 docker compose up -d。

六、环境变量表

镜像内与部署相关的环境变量（docker inspect 实测）：

变量默认值说明
PEERGOS_PATH/opt/peergos/data数据目录（镜像内已设好）；直跑形态下用于重定向 ~/.peergos
JAVA_HOME/opt/jre镜像内置 JRE 25 路径
PEERGOS_PASSWORD无shell/webdav/fuse 子命令的密码注入变量（避免交互输入）
PEERGOS_WEBDAV_PASSWORD无webdav 桥的 WebDAV 侧密码

说明：服务端没有通过环境变量注入业务配置的机制，全部业务参数走 daemon 命令行参数或持久化到 config 文件（见第七章）；JVM 堆在 compose entrypoint 行直接写死，无独立 JAVA_OPTS 变量。

七、配置参数说明

首次启动会把全部生效参数持久化到 data/config（实测节选，完整逐参数解读见《Peergos 1.41.0 配置参数详解》）：

port = 8000
listen-host = 0.0.0.0
default-quota = 1073741824
quota-upload-limit-seconds = 600
enable-gc = true
gc.period.millis = 43200000
useIPFS = true
global-download-bandwidth-limit = 1000000000
user-download-bandwidth-limit = 100000000
native-tweetnacl-path = /opt/peergos/native-libs/libtweetnacl.so
native-sqlite-path = /opt/peergos/native-libs/libsqlitejdbc.so

要点：

  • config 是权威配置源：重启后无需重复传命令行参数，直接 java -jar Peergos.jar daemon 即可；命令行参数优先于 config 中的值；
  • default-quota = 1073741824 即 1 GiB（字节单位）；
  • gc.period.millis = 43200000 即 12 小时一次块存储垃圾回收。

八、配置文件挂载

config 文件已在 bind mount 的 data/ 内，宿主机可直接编辑（本文环境即 ./data/config）。修改后重建服务生效：

docker compose restart

⚠️ 注意：config 内含 ipfs.identity.priv-key（服务器身份私钥）等敏感字段，宿主机上应 chmod 600 并纳入受限备份范围。

九、等价 docker run

不用 Compose 时的等价单命令（参数与本文 compose 完全一致）：

docker run -d --name peergos-1.41.0-server \
  --volume /opt/peergos/data:/opt/peergos/data \
  -p 8129:8000 \
  ghcr.io/peergos/web-ui:master \
  daemon -listen-host 0.0.0.0 -generate-token true -quota-upload-limit-seconds 600 -log-to-console true -public-domain 127.0.0.1:8129 -webroot server/webroot --native-tweetnacl-path /opt/peergos/native-libs/libtweetnacl.so --native-sqlite-path /opt/peergos/native-libs/libsqlitejdbc.so

公网域名 + TLS 形态（官方 README 原文写法，-public-domain 换成你的域名，TLS 由上游 nginx 终结）：官方命令为

docker run --volume $(PEERGOS_PATH):/opt/peergos/data ghcr.io/peergos/web-ui:master daemon -listen-host 0.0.0.0 -public-domain $YOUR_DOMAIN_NAME -public-server true -announce-ipfs-addresses /ip4/$IP/tcp/4001,/ip4/$IP/udp/4001/quic-v1 -log-to-console true

其中 -public-server true 允许公网 API 只读访问，-announce-ipfs-addresses 把公网 IP 与端口宣告进 p2p 网络；反向代理 nginx 的 TLS 配置官方推荐保留 /.well-known 转发并放通 8000 端口，且证书必须覆盖 域名 与 *.域名 通配符（应用子域需要）。

十、常用运维命令

# 状态/日志
docker compose ps
docker logs -f --tail 100 peergos-1.41.0-server

# 重启（配置文件改动后）
docker compose restart

# 停止/启动
docker compose stop
docker compose start

# 完全重建（数据在 bind mount 中不受影响）
docker compose down
docker compose up -d

# 服务端版本
docker exec peergos-1.41.0-server java -jar /opt/peergos/server/Peergos.jar version

version 实测回显：

Version: 1.41.0-web-ui/f5488655ac100ef6f0bc2e95340ee38c0d096b50

配额与用量的管理命令（quota/usage/admin）实测详见《Peergos 1.41.0 常用 CLI 命令与工具详解》第四章，常用两条：

docker exec peergos-1.41.0-server java -jar /opt/peergos/server/Peergos.jar quota show
docker exec peergos-1.41.0-server java -jar /opt/peergos/server/Peergos.jar usage show

usage show 实测回显：

peergos 0 B
demofriend 79673 B
demoadmin 100124 B

十一、常见问题

11.1 启动日志报 xdg-open IOException（SEVERE）

启动日志出现（实测节选）：

SEVERE: java.io.IOException: Cannot run program "xdg-open": Exec failed, error: 2 (No such file or directory)
	at peergos.server.DesktopApp.launch(DesktopApp.java:126)

原因：服务端完成启动后尝试调用系统浏览器打开 Web 界面，无桌面环境的服务器没有 xdg-open。该报错不影响任何服务功能（HTTP 服务照常 200），headless 服务器可忽略；需要自动弹浏览器再安装 xdg-utils。

11.2 首次启动很慢 / 卡在初始化

全新数据目录首次启动要同步全网 PKI（pki-state.cbor 镜像）并 bootstrap IPFS 路由，官方 troubleshooting 原文明示耗时数分钟；本文实测非首次重启约 1 分钟内 HTTP 就绪。判断方法：docker logs -f 看到 INFO Starting local Peergos server at: localhost:8000 与 Caching web-resources 即将就绪，随后 curl 返回 200。

11.3 浏览器能开登录页但应用子域功能报 Subdomain access blocked

实测日志样例：

SEVERE: Subdomain access blocked: [127.0.0.1:8129] not in 127.0.0.1:8000,0.0.0.0:8000,12D3KooW...,localhost:8000

原因：Peergos 的 Web 应用（PDF 查看器、文本编辑器等）通过子域隔离加载，-public-domain 参数值必须与浏览器实际访问的「主机:端口」一致。本文 compose 用 -public-domain 127.0.0.1:8129 对应本机回环访问场景；从其他机器访问时把该参数改为 服务器IP:8129（或正式域名）后 docker compose up -d 重建。

11.4 上传被拒绝（配额上传速率限制）

daemon 参数 -quota-upload-limit-seconds 600（本文 compose 显式设置）规定「上传完整个配额量至少需要 600 秒」，快速灌包会被拒。按需调大/调小该值或删掉该参数（默认不限）。

11.5 堆内存不足 / 想调整 JVM 内存

修改 compose entrypoint 行的 -Xms/-Xmx 后 docker compose up -d 重建，验证方法与回显见 4.5 节；容量规划与各参数详解见《Peergos 1.41.0 配置参数详解》。

十二、参考链接

  1. 官方 README 自托管章节（docker 形态）：https://github.com/Peergos/Peergos#usage---self-hosting-with-docker
  2. 官方镜像：https://ghcr.io/peergos/web-ui
  3. 官方发行页：https://peergos.net/public/peergos/releases
  4. 官方技术手册：https://book.peergos.org/
  5. 本专栏姊妹篇：《Peergos 1.41.0 配置参数详解》《Peergos 1.41.0 常用 CLI 命令与工具详解》《Peergos 介绍与选型指南》