Configuration

⚙️ 配置文件参考

主配置支持 TOML、YAML 和 INI。新部署推荐从 base/pref.example.toml 创建 base/pref.toml。

配置选择

程序参数：

-f <path>
--file <path>

官方启动脚本还支持 PREF_PATH。未指定时，启动脚本按平台查找 pref.toml、pref.yml、pref.ini，并在缺失时从对应示例创建配置。

配置来源优先级

通常按以下顺序理解：

1. 请求参数覆盖当前请求行为；
2. 受支持的环境变量覆盖配置文件；
3. 配置文件；
4. 程序兼容默认值。

只有部分配置项支持环境变量覆盖；请求参数不能绕过部署安全策略。具体例外见对应功能页面。

主要配置段

配置段	作用
[common]	默认输入、外部配置、基础模板、三类出站代理和通用行为
[proxy_provider]	Mihomo Provider 默认间隔和 proxy: DIRECT
[custom_openclash_rules]	COCR 服务端取源回落
[node_pref]	节点排序、过滤、名称和输出风格
[managed_config]	托管配置前缀、更新间隔和严格更新
[remote_subscription]	Surge、Surfboard、Loon 的客户端原生远程资源开关
[singbox]	Sing-box 目标行为
[security]	lan、public、strict 和公开上传
[statistics]	统计持久化、地理来源和 Dashboard 认证
[emojis]	Emoji 添加、删除和规则导入
[ruleset] / [[rulesets]]	规则生成和规则集列表
[[custom_groups]]	自定义策略组
[template]	模板路径和全局变量
[[aliases]]	URL 别名
[server]	监听地址、端口和静态文件根目录
[advanced]	日志、并发、资源限制、缓存、TLS 和请求合并

最小自部署配置

version = 1

[managed_config]
managed_config_prefix = "http://192.168.1.10:25500"

[security]
profile = "lan"
allow_public_upload = false

[statistics]
enabled = false

[server]
listen = "0.0.0.0"
port = 25500

实际配置仍需要保留示例文件中的模板、规则集和其他必要段。不要用上面的片段直接覆盖完整示例。

常用环境变量

环境变量	作用
PORT	覆盖监听端口
MANAGED_CONFIG_PREFIX	覆盖托管配置前缀
MANAGED_PREFIX	旧兼容名称；与新名称同时设置时优先新名称
SUBCONVERTER_SECURITY_PROFILE	覆盖安全档位
SUBCONVERTER_ALLOW_PUBLIC_UPLOAD	覆盖公开上传开关候选值
SUBCONVERTER_MAX_CONCURRENT_THREADS	覆盖基础并发线程数
SUBCONVERTER_MAX_SERVER_THREADS	覆盖 HTTP 最大线程数
SUBCONVERTER_DISABLE_COALESCING	禁用请求合并
SUBCONVERTER_COALESCE_RETRY_ON_5XX	控制合并请求首次 5xx 后的内部重试
SUBCONVERTER_RESPONSE_CACHE_TTL	覆盖 /sub 响应微缓存 TTL
SUBCONVERTER_DASHBOARD_CLIENT_IP_HEADER	Dashboard 可信代理客户端地址头
SUBCONVERTER_DASHBOARD_TRUSTED_PROXY_CIDRS	对应可信代理 CIDR

SUBCONVERTER_GIST_API_BASE 仅用于受控的 Gist API 入口，常规部署无需修改。

托管配置前缀

[managed_config]
managed_config_prefix = "https://sub.example.com"

它必须是客户端实际能够访问的地址。错误地保留 127.0.0.1 会让其他设备得到指向自身回环地址的更新链接。

服务器监听

[server]
listen = "0.0.0.0"
port = 25500

0.0.0.0 表示监听全部 IPv4 接口，不表示已经公网可达，也不表示安全。只允许本机访问时使用回环地址或在容器层只发布到回环地址。

资源限制和缓存

[advanced] 包含：

• 并发和 HTTP 线程上限；
• 规则集来源、规则数量和下载大小限制；
• 订阅、配置和规则集缓存；
• 异步规则抓取；
• 请求合并和 5xx 内部重试；
• TLS 校验迁移开关；
• 响应微缓存。

不要为了追求“更快”直接把限制设置为无限或盲目提高线程数。资源较小的主机应先观察内存、线程、文件描述符和请求延迟，再做有界调整。

advanced.allow_insecure_tls=false 应保持默认。它不是网络失败的通用重试开关。

热重载

common.reload_conf_on_request 会改变配置加载频率。启用前需要确认配置读取开销和并发行为；常规部署建议修改配置后显式重启服务，便于确认最终生效值。

验证配置来源

启动后检查日志中的：

• 配置格式已加载；
• 最终安全档位及来源；
• 上传策略；
• 并发和缓存参数；
• 监听地址和端口。

随后访问 /version 并执行真实 /sub。只看到进程运行不代表配置已经按预期加载。