Peergos 1.41.0 配置参数详解

目标：讲清 Peergos 1.41.0 服务端（daemon）全部启动参数与持久化配置文件的查看、修改方式与生效逻辑，按「监听与 Web、配额与限流、存储后端、p2p 组网、维护与可观测、JVM 内存」六大类逐参数详解，并给出可直接落地的生产配置模板。全部参数清单与示例值均在 Ubuntu 22.04 + Peergos 1.41.0 实测取得。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Peergos 版本：1.41.0（服务端 version 子命令实测回显 Version: 1.41.0-web-ui/f5488655ac100ef6f0bc2e95340ee38c0d096b50）
• 运行形态：jar 直跑（要求 Java >= 25；本文验证机为 openjdk 25.0.5 LTS）
• 安装布局：可执行文件 /opt/peergos/server/Peergos.jar，数据目录 /opt/peergos/data（由环境变量 PEERGOS_PATH=/opt/peergos/data 指定）
• 配置文件：/opt/peergos/data/config（首次启动自动生成，约 3.3KB）
• JVM 堆限制：-Xms256m -Xmx512m（实测 ps -ef 验证，见第十章）

二、前置条件

1. Peergos 服务端已安装并能启动（安装与部署全流程见《Peergos 1.41.0 Docker Compose 部署指南》，其镜像布局与本文目录布局一致）。
2. 知道 PEERGOS_PATH 指向的数据目录；本文所有服务端命令都在该目录所在机器执行。
3. Java 25+ 可用（java -version 确认）。

三、参数查看与修改方式

Peergos 的参数有两个来源，优先级为「命令行参数 > config 文件 > 内置默认值」：

方式 1：命令行 -help 实时查看全部参数（只读，最权威的参数名清单）。服务端 daemon 子命令的帮助输出实测如下（完整原文，参数名即 config 文件中的键名）：

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

daemon: The user facing Peergos server
Parameters:
	port: service port
	peergos.identity.hash: The hash of peergos user's public key, this is used to bootstrap the pki
	pki-node-id: Ipfs node id of the pki node
	pki.node.ipaddress: IP address of the pki node
	ipfs-api-address: IPFS API address
	ipfs-gateway-address: IPFS Gateway address
	proxy-target: Proxy target for p2p http requests
	ipfs-config-bootstrap-node-list: Comma separated list of IPFS bootstrap nodes.
	ipfs-announce-addresses: Comma separated list of extra announce multi-addresses. e.g. a public NAT address with port forwarding: /ip4/$IP/tcp/4001
	ipfs-previous-identity-swarm-port: Also run the identity this server rotated away from, on this port, for servers that still dial it. Give it the port the old identity used, and ipfs-swarm-port a new one.
	pki.node.swarm.port: Swarm port of the pki node
	listen-host: The hostname/interface to listen on
	public-domain: The public domain name for this server (required if TLS is managed upstream)
	useIPFS: Use IPFS for storage or a local disk store if not
	bat-store: The filename for the BAT store (or :memory: for ram based)
	partition-status-file: The filename for the partition status db
	allow-external-secret-links: Allow external secret links to be served from this server
	allow-external-login: Allow users from other servers to login through this server
	mutable-pointers-file: The filename for the mutable pointers datastore
	social-sql-file: The filename for the follow requests datastore
	space-requests-sql-file: The filename for the space requests datastore
	account-sql-file: The filename for the login datastore
	quotas-sql-file: The filename for the quotas datastore
	space-usage-sql-file: The filename for the space usage datastore
	link-counts-sql-file: The filename for the secret link counts datastore
	server-messages-sql-file: The filename for the server messages datastore
	transactions-sql-file: The filename for the transactions datastore
	quota-upload-limit-seconds: The minimum time period during which a user is allowed to upload their total quota, in seconds. Faster uploads will be rejected.
	global-download-bandwidth-limit: The maximum amount of data allowed to be downloaded from this server in bytes per second.
	global-s3-read-requests-limit: The maximum number of S3 read requests allowed from this server per second.
	user-download-bandwidth-limit: The maximum amount of data allowed to be downloaded per user in bytes per second.
	user-s3-read-requests-limit: The maximum number of S3 read requests allowed from this server per user per second.
	s3.versioned-bucket: If the S3 bucket is versioned
	serverids-file: The filename for the server ids datastore
	enable-gc: Enable the blockstore garbage collector
	gc.period.millis: Garbage collect frequency in millis (default 12h)
	webroot: the path to the directory to serve as the web root
	default-quota: default maximum storage per user
	admin-usernames: A comma separated list of usernames who can approve local space requests
	mirror.node.id: Mirror a server's data locally
	mirror.username: Mirror a user's data locally
	mirror.bat: BatWithId to enable mirroring a user's private data
	login-keypair: The keypair used to mirror the login data for a user (use with 'mirror.username' arg)
	public-server: Are we a public server? (allow http GETs to API)
	run-gateway: Run a local Peergos gateway
	gateway-port: Port to run a local gateway on
	unlisted-usernames: List of usernames removed from the auto-complete
	app-dev-target: URL for app assets for localhost app development
	collect-metrics: Export aggregated metrics
	metrics.address: Listen address for serving aggregated metrics
	metrics.port: Port for serving aggregated metrics
	ipfs.metrics.port: Port for serving aggregated ipfs metrics
	native-tweetnacl-path: Path to write the native TweetNaCl library, e.g. /opt/peergos/libtweetnacl.so. If not supplied a temp file is used. If the path is not writable but the file already exists, the existing file is loaded.
	native-sqlite-path: Path to write the native SQLite library, e.g. /opt/peergos/libsqlitejdbc.so. If not supplied a temp file is used. If the path is not writable but the file already exists, the existing file is loaded.

命令行传参格式为 -参数名 值，例如 -port 8000 -listen-host 0.0.0.0 -default-quota 10g。另有两个前缀风格并存：单横线长名（-quota-upload-limit-seconds）与双横线（--native-sqlite-path），help 中两类均出现，实测可混用。

方式 2：查看当前生效值——读 config 文件。首次启动会把全部生效参数持久化到 $PEERGOS_PATH/config，本文实测实例的 config（敏感令牌行已略，标注「实测节选」）：

account-sql-file = login.sql
bat-store = bats.sql
collect-metrics = false
daemon = true
default-quota = 1073741824
enable-gc = true
gateway-port = 9000
gc.period.millis = 43200000
generate-token = true
global-download-bandwidth-limit = 1000000000
global-s3-read-requests-limit = 100000
ipfs-api-address = /ip4/127.0.0.1/tcp/5001
ipfs-gateway-address = /ip4/127.0.0.1/tcp/8080
ipfs.identity.peerid = 12D3KooWErDT8pDRgAxGH4XekfNdHXpPmpyFawUKuGantuhgebhn
ipfs.identity.priv-key = CAESIIZIaQLCpjyblATiVl/T32EDtSzs2GzhtUu4vRBmGADW
listen-host = 0.0.0.0
log-to-console = true
metrics.address = localhost
metrics.port = 8001
mutable-pointers-file = mutable.sql
native-sqlite-path = /opt/peergos/native-libs/libsqlitejdbc.so
native-tweetnacl-path = /opt/peergos/native-libs/libtweetnacl.so
partition-status-file = partition-status.sql
peergos.identity.hash = z59vuwzfFDp3ZA8ZpnnmHEuMtyA1q34m3Th49DYXQVJntWpxdGrRqXi
pki-node-id = QmVdFZgHnEgcedCS2G2ZNiEN59LuVrnRm7z3yXtEBv2XiF
pki.node.ipaddress = 172.104.157.121
pki.node.swarm.port = 5001
port = 8000
proxy-target = /ip4/127.0.0.1/tcp/8003
public-server = false
quota-upload-limit-seconds = 600
quotas-sql-file = quotas.sql
s3.versioned-bucket = false
server-messages-sql-file = server-messages.sql
serverids-file = serverids.sql
social-sql-file = social.sql
space-requests-sql-file = space-requests.sql
space-usage-sql-file = space-usage.sql
transactions-sql-file = transactions.sql
useIPFS = true
user-download-bandwidth-limit = 100000000
user-s3-read-requests-limit = 1000

（输出节选说明：实测文件另含 device-token.<用户名> 设备令牌行与 link-counts-sql-file、serverids-file 等文件名键，属实例敏感信息与默认文件名，此处略去。）

修改方式：直接编辑 config（键 = 值，每行一条，# 注释），改完重启服务端生效；命令行参数只在当次运行覆盖对应键，重启后以 config 为准。推荐姿势：首次用命令行把参数调好 → 停服 → 确认 config 中键值正确 → 以后只用 java -jar Peergos.jar daemon 启动。

四、参数总览

按功能域分组（参数名、单位/格式、实测默认值、一句话作用）：

💡 技术拓展：useIPFS 背后是块存储后端选型——Peergos 支持「内置 IPFS（Nabu，默认）」「S3 兼容对象存储」「PostgreSQL 元数据」三类外置。S3 形态参数不在 daemon -help 清单内，官方 README 给出为：-use-s3 true -authed-s3-reads true -direct-s3-writes true -s3.accessKey <AK> -s3.bucket <桶> -s3.region <区域> -s3.region.endpoint <端点> -s3.secretKey <SK>，并注明 Minio 需 -authed-s3-reads false -direct-s3-writes false；PostgreSQL 形态参数为 -use-postgres true -postgres.database <库> -postgres.host <主机> -postgres.password <密码> -postgres.username <用户>（来源：官方 README「Usage - self hosting (with S3 compatible blockstore)/(with Postgres instead of sqlite)」，查询日期 2026-10-31）。本文实测实例采用默认内置 IPFS + SQLite，无需额外组件。

五、核心参数分类详解

5.1 监听与 Web 服务

• port（实测默认 8000）：Web 界面、API 与注册页共用端口。改端口后浏览器访问地址随之变化；若上游有 nginx 反代，保持此端口仅监听回环更安全。
• listen-host（实测 0.0.0.0）：仅本机访问用 127.0.0.1；局域网/公网访问必须 0.0.0.0 并放通防火墙对应端口。
• public-domain：告诉服务端「外部用户通过什么地址访问我」，值格式为 host:port（如 cloud.example.com:443）或域名。Web 应用子域（PDF 查看器、编辑器等）按此值校验来源，不一致会出现 Subdomain access blocked 日志（排障见第九章）。
• public-server（实测 false）：置 true 后允许匿名 HTTP GET API（公网服务器语义），通常与 -public-domain、TLS、-announce-ipfs-addresses 同时配置。
• webroot：Web 静态资源目录；镜像形态固定 server/webroot，jar 直跑形态默认从 jar 内读取，一般无需改动。
• run-gateway + gateway-port（实测 9000）：启用本地网关，可直接以子域方式托管存放在 Peergos 上的网站；不托管网站就不开。

5.2 配额与限流

• default-quota（实测 1073741824 = 1 GiB）：新注册用户默认配额，单位字节；命令行可用 -default-quota 10g 这种带后缀形式。存量用户配额用 quota set -username <用户> -quota <值> 即时调整（立即写库生效，无需重启，实测见《Peergos 1.41.0 常用 CLI 命令与工具详解》）。
• quota-upload-limit-seconds（实测 600）：限制「一个用户上传完其全部配额」所需的最短秒数，超出速率的整包上传被拒——防单用户瞬间灌满磁盘的保险丝。家庭/小团队可调小，公网开放注册必须保留。
• global-download-bandwidth-limit / user-download-bandwidth-limit（实测 1000000000 / 100000000 字节每秒）：全服与单用户下载速率上限，0 或不设为不限。
• global-s3-read-requests-limit / user-s3-read-requests-limit（实测 100000 / 1000 次每秒）：针对 S3 后端读请求的限流，保护对象存储配额与账单。
• admin-usernames：逗号分隔的用户名清单，这些用户可在 Web 界面审批本服务器的空间扩容请求（quota requests 流程）。
• generate-token（部署实测 true）：每次启动自动生成一枚注册令牌；配合 quota token create/count 手动管理。
• unlisted-usernames：从注册页自动补全中隐藏的用户名（例如内置 demo 账号）。
• allow-external-login / allow-external-secret-links：跨服务器登录与外部 secret link 代理开关，默认关闭；开放会扩大受攻击面，无需求不要开。

5.3 存储后端与数据文件

• useIPFS（实测 true）：块存储走内嵌 IPFS（Nabu）；false 时用本地磁盘块存储。绝大多数自托管保持默认。
• bat-store（实测 bats.sql）：BAT（Basic Attention Token 式付费授权）存储文件，个人部署用不到，保持默认。
• 11 个 SQLite 数据文件键：account-sql-file（登录）、quotas-sql-file（配额）、social-sql-file（好友/关注）、space-usage-sql-file（用量）、space-requests-sql-file（空间请求）、link-counts-sql-file（secret link 计数）、server-messages-sql-file（站内消息）、transactions-sql-file（事务）、serverids-file（服务器身份）、mutable-pointers-file（可变指针）、partition-status-file（分区状态）。文件名可改，本质是给多实例部署时错开文件用的；单实例保持默认。全部位于 $PEERGOS_PATH 下，备份时整目录打包即可。
• s3.versioned-bucket：改用 S3 后端时声明桶是否带版本控制，影响删除语义。

5.4 p2p 组网（IPFS/PKI）

• ipfs-api-address / ipfs-gateway-address（实测 /ip4/127.0.0.1/tcp/5001 与 /ip4/127.0.0.1/tcp/8080）：内嵌 IPFS 的 API/网关监听 multiaddr，保持回环即可，不要暴露公网。
• ipfs-swarm-port（默认 4001）与 ipfs-swarm-addrs：p2p 数据交换监听端口/完整 multiaddr 列表（后者优先）。NAT 后部署需把 4001 的 TCP+UDP 映射到公网。
• ipfs-announce-addresses：向网络宣告的额外可达地址。公网服务器必配：官方示例 -announce-ipfs-addresses /ip4/$IP/tcp/4001,/ip4/$IP/udp/4001/quic-v1。
• ipfs-config-bootstrap-node-list：引导节点表，实测 config 中为官方节点清单（libp2p bootstrap + Peergos 节点），一般不改。
• pki-node-id / pki.node.ipaddress / pki.node.swarm.port / peergos.identity.hash：PKI 引导四件套，首次启动按官方 PKI 节点写入 config（实测值见第三章 config 节选）。这些字段与 ipfs.identity.peerid、ipfs.identity.priv-key 共同构成服务器身份，删改会导致服务器身份丢失、无法再服务既有用户，严禁手工修改。
• ipfs-previous-identity-swarm-port：服务器身份轮换（server-identity rotate）后的过渡监听端口，让还在连旧身份的对端平滑切换。
• proxy-target（实测 /ip4/127.0.0.1/tcp/8003）：p2p HTTP 代理内部转发目标，保持默认。

5.5 维护与可观测

• enable-gc + gc.period.millis（实测 true + 43200000，即 12 小时）：块存储垃圾回收，删除文件后其块在 GC 后真正释放磁盘；小磁盘高频写入场景可调短周期（如 3600000 = 1 小时）。
• collect-metrics + metrics.address + metrics.port（实测 false + localhost + 8001）：聚合指标端点，配合 ipfs.metrics.port 可接 Prometheus 类抓取；默认关闭。
• log-to-console（部署实测 true）/ log-to-file（默认 true）：日志双通道；文件日志固定写 $PEERGOS_PATH/peergos.0.log 并滚动（peergos.1.log、peergos.2.log…）。
• print-log-location（quota/usage 等管理子命令参数）：启动时打印日志文件位置。

5.6 原生库与镜像参数

• native-tweetnacl-path / native-sqlite-path：TweetNaCl 与 SQLite 的 JNI 原生库落盘路径。不指定时每次启动写临时目录；指定到固定路径（如 /opt/peergos/native-libs/，目录不可写但文件已存在时直接加载现有文件）可避免重复释放并配合只读部署。实测 config 值见第三章。
• mirror.node.id / mirror.username / mirror.bat / login-keypair：把另一台服务器（或某用户）的数据持续镜像到本机的四个参数，取值来自 mirror init 子命令输出，属高级迁移/容灾场景（官方 README Mirror 一节）。

六、生产配置模板

适用场景：8GB 内存、NVMe SSD、5–20 人团队/家庭的常驻自托管服务器，块存储用内置 IPFS + 本地盘，元数据 SQLite，公网域名 + nginx TLS 终结。/opt/peergos/data/config（在自动生成 config 基础上核对/修改以下键）：

# 监听与对外
port = 8000
listen-host = 0.0.0.0
public-server = true
public-domain = cloud.example.com:443
webroot = server/webroot

# 配额与限流
default-quota = 10737418240
quota-upload-limit-seconds = 600
global-download-bandwidth-limit = 2000000000
user-download-bandwidth-limit = 200000000
admin-usernames = admin

# 存储与回收
useIPFS = true
enable-gc = true
gc.period.millis = 43200000

# p2p 组网（把 4001 的 TCP/UDP 映射到公网后填写本机公网 IP）
ipfs-announce-addresses = /ip4/203.0.113.10/tcp/4001,/ip4/203.0.113.10/udp/4001/quic-v1

# 原生库
native-tweetnacl-path = /opt/peergos/native-libs/libtweetnacl.so
native-sqlite-path = /opt/peergos/native-libs/libsqlitejdbc.so

模板要点：public-server + public-domain 成对出现（TLS 由 nginx 终结，证书需覆盖 cloud.example.com 与 *.cloud.example.com）；default-quota 按磁盘容量 ÷ 预期用户数取值；admin-usernames 必须配置否则没人能审批空间请求；ipfs-announce-addresses 填公网 IP（示例 203.0.113.10 换成实际值），NAT 内网部署则删除该行并依赖默认打洞。

七、JVM 内存参数与生效验证

服务端是 Java 进程，堆内存必须显式限制在 256–512MB（默认不限制会随负载吃大内存）。修改位置按托管形态：

1. 直跑/脚本启动：java 启动行直接加参数——

java --enable-native-access=ALL-UNNAMED -Xms256m -Xmx512m -jar /opt/peergos/server/Peergos.jar daemon

2. systemd 托管：服务单元中用 JAVA_OPTS 环境变量注入（每行仅一个 Environment=），启动行引用——

[Service]
Environment=JAVA_OPTS=-Xms256m -Xmx512m
ExecStart=/usr/bin/java --enable-native-access=ALL-UNNAMED ${JAVA_OPTS} -jar /opt/peergos/server/Peergos.jar daemon

3. 容器编排形态：在编排文件的 java 启动命令行中写死 -Xms256m -Xmx512m（写法与验证见《Peergos 1.41.0 Docker Compose 部署指南》4.5 节）。

生效验证（实测回显，ps -ef 可见完整命令行中的堆参数；无 jps 的最小环境用此法兜底）：

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

有 JDK 环境时可用 jps -v 得到同样的参数视图（jps -v 输出中直接列出 -Xms256m -Xmx512m）；极端情况下（怀疑 JVM 因运行环境感知机制忽略手工参数，如启用了 -XX:+UseContainerSupport 自动按内存上限设堆）用上述 ps -ef 看真实命令行为准。

八、常见问题

8.1 改了 config 但没生效

命令行参数优先于 config：启动命令里带了 -port 8001 之类参数时，config 中的 port 会被覆盖。核对实际启动命令（ps -ef | grep [P]eergos）与 config 值是否冲突；固定用 java -jar Peergos.jar daemon（无参）启动即可完全依赖 config。

8.2 如何单独改某个用户的配额（不想动全局默认）

配额不走 config，用管理命令即时生效：java -jar Peergos.jar quota set -username <用户> -quota 5g，验证 quota show -username <用户> 实测返回 demofriend 5 GiB（完整回显见《Peergos 1.41.0 常用 CLI 命令与工具详解》第四章）。default-quota 只影响之后的新注册用户。

8.3 Subdomain access blocked

public-domain 与浏览器实际访问地址不一致导致（Web 应用按子域隔离加载）。把 public-domain 改成用户实际访问的 主机:端口（或域名）后重启。

8.4 首次启动慢

首次启动同步全网 PKI（下载镜像 pki-state.cbor）耗时数分钟，官方 troubleshooting 原文明示；此后启动秒级。观察 peergos.0.log 中 Starting local Peergos server at: 出现即接近就绪。

8.5 日志在哪

文件日志 $PEERGOS_PATH/peergos.0.log（滚动 peergos.1.log…，各 1MB 左右）；log-to-console true 时同步输出到标准输出（systemd 下进 journald）。

九、参考链接

1. 官方 README（自托管/S3/Postgres 形态参数）：https://github.com/Peergos/Peergos#usage---self-hosting
2. 官方技术手册：https://book.peergos.org/
3. 官方发行页：https://peergos.net/public/peergos/releases
4. 姊妹篇：《Peergos 1.41.0 Docker Compose 部署指南》《Peergos 1.41.0 常用 CLI 命令与工具详解》