model.md

title	配置模型
description	理解 SynapS3 配置来源、默认值、可编辑设置和高风险字段。

配置模型

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 必须保存在受保护的配置或密钥存储中。

主要配置段

配置段	用途
server	S3 API 监听、并发限制和 TLS 字段。
s3	返回给 S3 客户端的 region。
filecoin	网络、RPC、钱包、存储提供方 URL 策略、CDN hints 和副本策略。
filecoin.observability	存储提供方和本地数据集健康检查。
database	SQLite 或 PostgreSQL 元数据数据库。
cache	本地对象缓存目录、容量和淘汰策略。
worker.upload	后台 Filecoin 存储并发、轮询和重试。
worker.evictor	本地缓存淘汰任务。
worker.storage_cleanup	远端副本清理任务。
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	4
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.upload.concurrency	4
worker.upload.max_retries	5
admin.addr	127.0.0.1:9090
admin.trusted_proxies	[]
admin.auth.enabled	true
admin.auth.username	admin
admin.auth.session_ttl	12h

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：所有目标远端副本提交后，该版本会在下一次 Evictor 轮询时加入清理。之后从远端读取并回填的缓存不会再次被立即删除。
• 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