配置模型

SynapS3 先读取 TOML 配置，再应用 SYNAPS3_ 环境变量覆盖。稳定设置建议写在配置文件中；密钥和部署专用设置更适合放在环境变量里。

来源规则

• 不传 --config 时，SynapS3 读取 ~/.synaps3/config.toml。
• 使用 --config <path> 指定其他文件。
• 当前目录中的 config.toml 不会自动读取，除非显式传入。
• synaps3 init --dir <path> 会创建文件，但不会改变默认配置来源。
• Admin settings 写入会重写 config.toml；注释和顺序不会保留。

查看当前生效设置：

synaps3 admin settings get

输出会显示配置路径、是否允许写入，以及是否需要重启。

保存设置后，重启 SynapS3，检查 /healthz，再运行 synaps3 admin settings get，确认实际生效值。

必需密钥

正常启动服务前，需要设置 Filecoin 钱包私钥：

[filecoin]
private_key = "0x..."

也可以用 SYNAPS3_FILECOIN_PRIVATE_KEY 管理这个值；支持的覆盖项见环境变量。

不要把私钥放进代码仓库、容器镜像或 shell history。

当 admin.auth.enabled = true 时，Admin 认证还需要密码 hash 和 admin.auth.session_secret。新配置会由 synaps3 init 创建；如果缺失或需要轮换密码，运行 synaps3 admin-auth reset-password --config <path> 重新生成。重置密码也会轮换 session secret。

配置、.env 和凭据文件都应保持 0600 权限。

S3 服务

S3 API 通过以下字段支持原生 TLS：

[server.tls]
enabled = true
cert_file = "/path/to/tls.crt"
key_file = "/path/to/tls.key"

证书和私钥必须允许 SynapS3 进程读取。在容器部署中，配置的路径必须存在于容器内，通常通过只读挂载提供。生产 S3 流量必须使用原生 TLS 或受控的 TLS 反向代理。

Admin 端点有独立的暴露范围控制。让 admin.addr 保持回环地址、使用 SSH 隧道，或放在带访问控制的 HTTPS 反向代理之后。

数据库选择

SQLite 是 SynapS3 单机部署的默认且推荐数据库。已有 PostgreSQL 运维体系或需要外置元数据数据库时，可以使用 PostgreSQL；其 DSN 必须保存在受保护的配置或密钥存储中。

database.max_open_conns 决定连接池大小。SQLite 同一时刻仍只有一个连接能写入，其余连接用于读取；写入遇到数据库忙时最多等待 5 秒（busy_timeout），超时则以 SQLITE_BUSY 失败。

主要配置段

配置段	用途
server	S3 API 监听、并发限制和 TLS 字段。
s3	返回给 S3 客户端的 region。
filecoin	网络、RPC、钱包、存储提供方 URL 策略、CDN hints 和副本策略。
filecoin.observability	存储提供方和本地数据集健康检查。
database	SQLite 或 PostgreSQL 元数据数据库。
cache	本地对象缓存目录、容量和淘汰策略。
worker.tasks	统一后台任务执行、恢复、保留时间和存储变更并发限制。
logging	运行时日志等级、格式和 S3 access log。
admin	仪表盘、Admin API 监听地址和 Admin 认证设置。

重要默认值

字段	默认值
server.port	:8080
server.max_connections	4096
server.max_requests	512
s3.region	us-east-1
filecoin.network	calibration
filecoin.default_copies	3
database.driver	sqlite
database.max_open_conns	32
database.max_idle_conns	2
cache.max_size_gb	100
cache.eviction_policy	lru
cache.lru_high_watermark_percent	90
cache.lru_low_watermark_percent	80
worker.tasks.concurrency	12
worker.tasks.poll_interval	5s
worker.tasks.lease_duration	5m
worker.tasks.max_retries	5
worker.tasks.retention	168h
worker.tasks.provider_mutation_concurrency	4
worker.tasks.destructive_mutation_concurrency	2
admin.addr	127.0.0.1:9090
admin.trusted_proxies	[]
admin.auth.enabled	true
admin.auth.username	admin
admin.auth.session_ttl	12h

worker.tasks.concurrency 限制全部后台操作。创建远端存储、Store、Pull 和提交存储承诺共同受 provider_mutation_concurrency 限制；远端清理与服务退休共同受 destructive_mutation_concurrency 限制。状态和确认查询不占用这些变更并发额度。钱包变更始终串行执行。操作遇到对应额度已满时会先让出、稍后自动再试，不占用 concurrency 名额，其他后台任务照常运行。任务设置修改后必须重启 SynapS3，已经创建的任务保留创建时记录的重试上限。

Admin 会话时长

admin.auth.session_ttl 控制每个普通 Admin UI 会话 token 的有效时长，既不是服务端强制的空闲超时，也不是一次登录的绝对上限。经过 5 分钟或 token 有效时长的一半（取较短者）后，服务端允许续期。官方仪表盘只在可信的指针、点击、键盘或滚轮操作后请求续期；后台轮询和仅切回可见标签页不会触发续期。任何持有有效 session cookie 和对应 CSRF token 的客户端，都可以在 refresh_after 之后调用续期接口。没有客户端请求续期时，token 会在 expires_at 到期。

登录页默认使用 browser-session cookie。选择 Keep me signed in 后，会改用持久 cookie，并使用 30 天或 admin.auth.session_ttl 中较长的时长。只要仪表盘持续收到用户操作，就可以继续请求续期；服务端不设置登录的绝对时长上限。

允许值

• filecoin.network: calibration, mainnet。
• filecoin.default_copies: 1 到 8。
• database.driver: sqlite, postgres。
• cache.eviction_policy: lru, after_upload, none。
• logging.level: debug, info, warn, error。
• logging.format: json, text。
• admin.trusted_proxies: IP 或 CIDR。除非可信反向代理会清理不可信 forwarded headers，否则保持空。

缓存淘汰策略会产生以下用户可见结果：

• lru：缓存使用量达到高水位后，SynapS3 按最近访问时间淘汰最久未使用且远端安全的条目，直到降至低水位。
• after_upload：版本达到其存储桶要求的最低耐久副本数后，会加入异步清理。之后从远端读取并回填的缓存不会再次被立即删除。
• none：SynapS3 不会自动清理本地缓存。

LRU 水位始终必须满足 0 <= low < high <= 100。在 after_upload 或 none 下仍会保存这些值，但不会生效。

[cache]
eviction_policy = "lru"
lru_high_watermark_percent = 90
lru_low_watermark_percent = 80

淘汰设置会在重启后生效。缓存清理是异步流程；PutObject 不会同步等待或触发一次 LRU 检查。

高风险字段

字段	风险
admin.addr	暴露 Admin API 会允许运维写操作。除非有 HTTPS 和访问控制保护，否则保持本机回环地址。
admin.trusted_proxies	对匹配代理信任 X-Forwarded-For、X-Real-IP、X-Forwarded-Proto 和 X-Forwarded-Host。只配置你控制的代理。
Admin password hash	控制 Admin 登录。不要手动配置；用 synaps3 init 或 synaps3 admin-auth reset-password 生成。
admin.auth.session_secret	用于签名 Admin 浏览器会话。按密钥处理。
filecoin.private_key	控制钱包支付和存储操作。必须作为私钥处理。
database.dsn	可能包含数据库凭据，必须作为敏感值处理。
filecoin.network	切换到 mainnet 会改变支付和存储环境。
filecoin.allow_private_networks	允许私有网络存储提供方 URL。只在可信私有部署中开启。
cache.max_size_gb	太小会阻塞写入；太大会占满主机磁盘。
cache.lru_high_watermark_percent	高水位过高会减少淘汰追赶期间可供新写入使用的余量。
cache.lru_low_watermark_percent	低水位过低会让每轮 LRU 清理更多缓存数据。

高风险设置可能需要显式确认：

synaps3 admin settings set filecoin.network=mainnet --yes