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. 程序兼容默认值。

只有部分配置项支持环境变量覆盖；请求参数不能绕过部署安全策略或已关闭的功能总开关。例如，Emoji 请求参数受下方 Emoji 总开关约束。

主要配置段

配置段	作用
[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 和请求合并

Emoji 总开关

从 v1.11.1 起，主配置中的 emojis.enabled 控制后端是否执行内置 Emoji 添加和清理。它是部署级配置，不是 /sub 请求参数，也不能由 config= 指定的外部配置启用。

字段	类型	缺省值	作用
enabled	布尔	false	允许内置 Emoji 添加和清理；关闭时下方两个开关及请求、外部配置中的开关均不能启用处理
add_emoji	布尔	false	总开关开启后，服务端解析节点时是否默认添加 Emoji
remove_old_emoji	布尔	false	总开关开启后，服务端解析节点时是否默认清理旧 Emoji

TOML：

[emojis]
enabled = false

INI：

[emojis]
enabled=false

YAML：

emojis:
  enabled: false

将实际使用的主配置中的 enabled 设为 true，才能恢复原有 Emoji 处理。保留已有的规则和添加、清理配置；开启总开关本身不会为 Provider 自动添加 Emoji，仍需在请求中明确传入 emoji=true。

关闭或缺少 enabled 字段时，Provider、服务端解析、list=true 和混合输入中的直接节点均停止内置 Emoji 处理。请求中的 emoji、add_emoji、remove_emoji 会被忽略，外部配置和 pref 中的添加、清理开关也不能重新启用处理。旧配置无需补字段即可正常加载，但缺省关闭会改变原有 Emoji 处理结果。

正常 rename 规则继续执行；若 rename 本身包含 Emoji 替换，仍会按规则修改名称。规则来源、Provider 参数语义和客户端更新方法见 Emoji 与 Provider 名称处理。

修改配置后，重启服务或重新创建容器，并用请求诊断确认生效状态。配置被重新加载时，删除 enabled 字段会恢复关闭。升级注意事项见升级、回滚与迁移。

最小自部署配置

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_RESOURCE_CONTROL	覆盖 advanced.resource_control
SUBCONVERTER_FORCE_MAX_CURVE_FINGERPRINT	覆盖已弃用的 advanced.force_max_curve_fingerprint；仅保留诊断兼容性
SUBCONVERTER_REQUEST_DEADLINE_MS	覆盖整个 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.resource_control 支持三个值：

值	用户可见行为
compat	默认值。使用同步、有界的兼容路径，并保留显式配置的基础线程和等待队列限制。
adaptive	使用协作式异步转换路径，并根据可观测的 CPU、内存压力和文件描述符状态管理并发。
force_max	面向公共服务的最大吞吐模式。根据完整探测到的 CPU、内存、PID 和文件描述符边界，在监听前应用确定且有界的完整启动预算；必要资源或运行组件无法验证时拒绝启动。

未知值会导致启动失败，不会静默改用其他模式。force_max_curve_fingerprint 是已弃用的诊断兼容项；是否填写或匹配均不会改变 force_max 容量，新部署应保持为空。

公共服务部署建议在完成资源隔离、压力测试和监控后评估启用 force_max。个人私有部署通常不建议启用。完整用途、资源代价、配置方法、验证和回退步骤见 force_max 性能模式。

正式 Release 配置示例中的相关值：

配置项	示例值	说明
resource_control	compat	资源控制模式
max_pending_connections	10240	普通模式的 HTTP 等待队列上限；force_max 应用预算时由程序重新计算
max_concurrent_threads	16	普通模式的 HTTP 基础工作线程数；force_max 应用预算时由程序重新计算
max_server_threads	128	普通模式的 HTTP 动态工作线程总上限；force_max 应用预算时由程序重新计算

资源容量相关配置在运行期间冻结，修改后需要重启进程。不要为了追求“更快”直接把限制设为无限或盲目提高线程数。调整前先观察内存、CPU 压力、文件描述符、队列和请求延迟。

请求截止时间

advanced.request_deadline_ms 限制整个 HTTP 请求的绝对处理时间，单位为毫秒。正式 Release 配置示例为 15000；SUBCONVERTER_REQUEST_DEADLINE_MS 可覆盖该值。程序会把有效值收敛到 100～300000 毫秒。

该值不是单次远程下载超时，也不是客户端等待时间；它是服务端对当前 HTTP 请求的总截止时间。降低前需考虑订阅与规则来源的正常延迟；提高前需考虑并发请求对线程、连接和内存的占用。

下载缓存与响应微缓存

配置项	示例值	影响
enable_cache	true	控制订阅、外部配置和规则集下载缓存；设为 false 时，下列三个 TTL 都按 0 处理
cache_subscription	60	订阅下载缓存 TTL，单位秒
cache_config	300	外部配置及通用配置资源缓存 TTL，单位秒
cache_ruleset	21600	规则集下载缓存 TTL，单位秒
response_cache_ttl	0	符合请求合并条件、未启用 Age 加密的 200 /sub 响应微缓存；0 关闭，正值最大收敛为 5 秒

response_cache_ttl 与三类下载缓存相互独立；enable_cache=false 不会自动关闭响应微缓存。SUBCONVERTER_RESPONSE_CACHE_TTL 可覆盖响应微缓存 TTL。

advanced.max_allowed_rulesets 在 TOML、YAML 和 INI 正式示例中统一为 64。0 表示不限制，但公网服务不应在没有对应内存、下载大小和请求截止策略时使用无限制。

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

热重载

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

验证配置来源

启动后检查日志中的：

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

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