| title | 环境变量 |
|---|---|
| description | 使用 SYNAPS3 环境变量覆盖配置，并理解适用场景。 |
配置环境变量使用 SYNAPS3_ 前缀，下划线会映射到配置路径。环境变量会覆盖文件值，适合放部署密钥和主机专用设置。
| 环境变量 | 配置路径 |
|---|---|
SYNAPS3_SERVER_PORT |
server.port |
SYNAPS3_SERVER_MAX_CONNECTIONS |
server.max_connections |
SYNAPS3_SERVER_MAX_REQUESTS |
server.max_requests |
SYNAPS3_SERVER_TLS_ENABLED |
server.tls.enabled |
SYNAPS3_SERVER_TLS_CERT_FILE |
server.tls.cert_file |
SYNAPS3_SERVER_TLS_KEY_FILE |
server.tls.key_file |
SYNAPS3_S3_REGION |
s3.region |
SYNAPS3_FILECOIN_NETWORK |
filecoin.network |
SYNAPS3_FILECOIN_RPC_URL |
filecoin.rpc_url |
SYNAPS3_FILECOIN_PRIVATE_KEY |
filecoin.private_key |
SYNAPS3_FILECOIN_WITH_CDN |
filecoin.with_cdn |
SYNAPS3_FILECOIN_ALLOW_PRIVATE_NETWORKS |
filecoin.allow_private_networks |
SYNAPS3_FILECOIN_DEFAULT_COPIES |
filecoin.default_copies |
SYNAPS3_FILECOIN_OBSERVABILITY_INTERVAL |
filecoin.observability.interval |
SYNAPS3_FILECOIN_OBSERVABILITY_TIMEOUT |
filecoin.observability.timeout |
SYNAPS3_FILECOIN_OBSERVABILITY_CONCURRENCY |
filecoin.observability.concurrency |
SYNAPS3_DATABASE_DRIVER |
database.driver |
SYNAPS3_DATABASE_DSN |
database.dsn |
SYNAPS3_DATABASE_MAX_OPEN_CONNS |
database.max_open_conns |
SYNAPS3_DATABASE_MAX_IDLE_CONNS |
database.max_idle_conns |
SYNAPS3_CACHE_DIR |
cache.dir |
SYNAPS3_CACHE_MAX_SIZE_GB |
cache.max_size_gb |
SYNAPS3_CACHE_EVICTION_POLICY |
cache.eviction_policy |
SYNAPS3_CACHE_LRU_HIGH_WATERMARK_PERCENT |
cache.lru_high_watermark_percent |
SYNAPS3_CACHE_LRU_LOW_WATERMARK_PERCENT |
cache.lru_low_watermark_percent |
SYNAPS3_WORKER_UPLOAD_CONCURRENCY |
worker.upload.concurrency |
SYNAPS3_WORKER_UPLOAD_POLL_INTERVAL |
worker.upload.poll_interval |
SYNAPS3_WORKER_UPLOAD_MAX_RETRIES |
worker.upload.max_retries |
SYNAPS3_WORKER_EVICTOR_CONCURRENCY |
worker.evictor.concurrency |
SYNAPS3_WORKER_EVICTOR_POLL_INTERVAL |
worker.evictor.poll_interval |
SYNAPS3_WORKER_EVICTOR_MAX_RETRIES |
worker.evictor.max_retries |
SYNAPS3_WORKER_STORAGE_CLEANUP_CONCURRENCY |
worker.storage_cleanup.concurrency |
SYNAPS3_WORKER_STORAGE_CLEANUP_POLL_INTERVAL |
worker.storage_cleanup.poll_interval |
SYNAPS3_WORKER_STORAGE_CLEANUP_MAX_RETRIES |
worker.storage_cleanup.max_retries |
SYNAPS3_LOGGING_LEVEL |
logging.level |
SYNAPS3_LOGGING_FORMAT |
logging.format |
SYNAPS3_LOGGING_S3_ACCESS_ENABLED |
logging.s3_access.enabled |
SYNAPS3_LOGGING_S3_ACCESS_LEVEL |
logging.s3_access.level |
SYNAPS3_ADMIN_ADDR |
admin.addr |
SYNAPS3_ADMIN_TRUSTED_PROXIES |
admin.trusted_proxies |
SYNAPS3_ADMIN_AUTH_ENABLED |
admin.auth.enabled |
SYNAPS3_ADMIN_AUTH_USERNAME |
admin.auth.username |
SYNAPS3_ADMIN_AUTH_SESSION_SECRET |
admin.auth.session_secret |
SYNAPS3_ADMIN_AUTH_SESSION_TTL |
admin.auth.session_ttl |
SYNAPS3_ADMIN_TRUSTED_PROXIES 是逗号分隔的 IP 或 CIDR 列表。
| 环境变量 | 配置路径 |
|---|---|
SYNAPS3_ADMIN_AUTH_PASSWORD_HASH |
admin.auth.password_hash |
admin.auth.password_hash 通常由 synaps3 init 或 synaps3 admin-auth reset-password 生成。除非外部流程已经接管 Admin 密码 hash，否则不要手写。
下面这些变量不映射到 TOML 配置字段。
| 环境变量 | 用途 |
|---|---|
SYNAPS3_DATA_DIR |
自动执行 synaps3 init 时使用的运行数据目录；默认是 /var/lib/synaps3。 |
SYNAPS3_CONFIG |
CLI 命令在未传 --config 时使用的配置文件；Compose 示例默认使用 /var/lib/synaps3/config.toml 且允许覆盖，entrypoint 启动 serve 时默认使用 $SYNAPS3_DATA_DIR/config.toml。 |
SYNAPS3_ADMIN_PASSWORD |
仅用于 CLI 认证的 Admin 密码。优先使用终端无回显提示或受保护的密钥来源，不要让密码进入 shell history。 |
适合放在环境变量中的内容：
- 钱包私钥和数据库 DSN，
- 外部管理的 Admin session secret，
- 容器专用路径，
- 网络特定 RPC URL，
- 部署特定日志格式，
- 排障期间的临时覆盖。
稳定设置如果希望在 synaps3 admin settings get 中清楚展示，建议放在 TOML 配置文件中。SYNAPS3_DATA_DIR 只用于 Docker entrypoint 路径控制；SYNAPS3_CONFIG 适合让容器内命令复用同一个配置文件。
Warning
不要把钱包私钥、数据库凭据、Admin 密码和 Admin session secret 放进 git、容器镜像或 shell history。
- 将
SYNAPS3_FILECOIN_PRIVATE_KEY放在密钥管理系统、.env或主机环境中。synaps3 init和synaps3 admin-auth reset-password会生成admin.auth.session_secret；只有部署策略要求在 TOML 外管理时，才使用SYNAPS3_ADMIN_AUTH_SESSION_SECRET。 - 把
SYNAPS3_DATABASE_DSN、SYNAPS3_ADMIN_PASSWORD和SYNAPS3_ADMIN_AUTH_SESSION_SECRET作为敏感值处理。只要条件允许，就通过 CLI 的无回显提示输入 Admin 密码。 - 让
.env、config.toml和凭据文件保持0600权限。 - 除非可信代理会在请求到达 SynapS3 前清理不可信 forwarded headers，否则保持
SYNAPS3_ADMIN_TRUSTED_PROXIES为空。 - 不要提交
.env、config.toml、本地数据库、缓存数据或钱包材料。 - 除非明确信任私有存储提供方 URL，否则保持
filecoin.allow_private_networks = false。 - 环境变量管理的字段会覆盖文件值；只改文件不会改变这些字段的生效值。
synaps3 admin settings get输出会显示当前值，以及每个设置是否可写。
修改设置后，重启 SynapS3，检查 /healthz，再运行此命令确认实际生效值。环境变量仍会覆盖文件值。