9.5 KiB
订阅、插件与监听配置
订阅资料
面向订阅服务提供方的字段格式、嵌套分组扩展和响应要求见 SIP-008 订阅扩展说明。
订阅可在 SIP-008 JSON 根级提供 bytes_used、bytes_remaining（非负整数，最大为 UInt64），以及自定义的 expires_at（服务到期时间）、traffic_reset_at（流量重置时间）。日期值使用 RFC 3339 字符串，省略或 null 表示未提供；无效资料仅忽略该项，不影响有效服务器或分组资料。
成功刷新完整替换白名单订阅资料，省略或无效的字段清除旧值；失败或取消保留最后成功资料与独立成功时间。资料和目录记录同文档原子保存，不另存原始响应或含密码的服务器明文快照；密码和插件参数沿用 Keychain 存储。旧目录文件缺少成功时间时不猜测。
订阅卡片显示返回的有效资料；仅在两项流量都有效且总量大于零时显示消耗进度。日期按用户当前语言与时区显示，到期和重置资料不改变代理启停或激活行为。
用户插件目录
PluginCatalog 合成当前托管清单与本机 plugins.json 用户记录，名称精确区分大小写。用户映射优先，失效 override 不退回托管程序；删除 override 恢复当前 app 默认值。文件读取错误保留阻断事实，不按空映射处理。用户路径、本地启动参数与插件传输模式不进入服务器资料、订阅或分享文件。用户路径也不进入诊断报告。
设置页底部的“插件”区域统一展示内置与用户插件，按记录展示全部名称，支持新增、编辑名称集合与路径、逐名称覆盖内置、删除记录与恢复同名内置。用户与内置记录可以设置插件传输模式 tcp_only 或 tcp_and_udp；默认 tcp_only，生成 sslocal 配置时省略 plugin_mode。应用不探测插件的 SIP003u 支持。内置编辑器中的“清空参数”只清空草稿启动参数并保留模式，保存后生效。名称与启动参数使用列表编辑，启动参数保留顺序和完整字符串；路径支持手动输入与文件选择。读取失败时隐藏条目并提供只读重试，管理 UI 不提供整体重置。映射提交与显式修复 interface 在组合根统一接入表单、激活与诊断。保存成功后刷新激活候选并异步收敛，运行失败不撤销保存。没有文件替换监控。plugins.json v1 每项独立迁移为带持久身份的用户记录，下一次保存写入 v2，不按相同路径合并。现有内置程序同时提供 v2ray-plugin 和 v2ray-plugin-v1。详见 ADR-0033。
MacOSPluginInspection 只读取下载隔离、签名与系统评估事实，不启动用户插件、不修改系统策略。检查失败或不适用为未知；策略评估拒绝不等于实际执行禁令，也不阻止映射保存或激活。真实 macOS 拦截提示不由 hostless 替身测试证明。
Cloak 托管插件
随应用提供官方 Cloak v2.12.0 的 darwin-arm64 ck-client，服务器引用名称为 cloak 或 cloak-v2，两者共享一条内置记录。ck-client 是打包文件名，不是可引用名称。同名用户插件仍优先；失效覆盖不会自动回退到内置程序。
服务器插件选项原样传给上游，不进行 Cloak 字段语义校验。可以使用分号分隔的 Key=value 参数，或使用外部 JSON 配置文件的绝对路径。外部文件由用户维护，应用不复制文件、不管理文件凭据或生命周期；分享路径不包含文件内容，接收方需要自行提供对应文件。本地启动参数仍独立保存，不随服务器资料分享。
固定版本配置解析存在以下限制：只有同时含 ; 和 = 的字符串才被识别为参数列表，单个 Key=value 会被当作文件路径；转义分号仍会被切分，引号和反斜杠也不能按通用 SIP003 转义方式可靠传递；空段会终止后续解析。需要复杂值时可自行维护 JSON 文件。提供 UID、PublicKey、ServerName、EncryptionMethod，并按需显式设置 NumConn=4，不能依赖 README 所述的默认 4；省略时固定版本实现关闭连接复用。显式端点字段会覆盖 SIP003 环境变量，因此通常应省略 LocalHost、LocalPort、RemoteHost、RemotePort。
默认插件传输模式为 tcp_only。上游 UDP=true 切换为 UDP 监听，不代表同时承载 TCP 与 UDP 的 SIP003u 支持；应用仍允许用户设置现有传输模式，本次只验收 TCP 配置接入。托管程序的 GPL-3.0 许可证、来源与第三方声明随应用装入 Contents/Resources/ThirdParty/Cloak/，源码与构建入口见其中 NOTICE。
本地与局域网监听
后台代理客户端运行时，本地 SOCKS/HTTP 始终监听 127.0.0.1，默认端口为 11086/11087；本地 SOCKS 固定开启 UDP 中继。局域网入口默认关闭，使用独立端口 11088/11089，支持 IPv4、双栈和仅 IPv6 三种方式。四端口必须在 1025...65535 内且全部不同。
局域网 SOCKS 的 UDP 中继和 SOCKS/HTTP 共用的身份验证独立设置。用户名与密码随监听配置整体加密保存，Keychain 仅保存监听专用主密钥；运行时派生当前用户专用的认证文件；上游认证失败日志中的密码会隐藏。设置只检查 TCP 占用，不设置独立 UDP 端口。首页命令按选择地址使用本地或局域网端口，局域网身份验证开启时加入编码后的凭据；tooltip 显示完整命令。
监听配置使用标准 age 文件格式与独立 X25519 identity，单独加密保存在 proxy-listening.age，只包含本地与局域网监听相关值。代理模式、规则默认动作、代理服务开关、系统代理开关和附加系统代理例外以 proxyControl. 前缀的独立键保存在 UserDefaults；运行计算的内存快照不代表统一持久化文档。监听仍采用联合校验与原子文件保存；UserDefaults 偏好不提供同步落盘失败的报错与回滚。
不迁移旧 settings.json：新监听文件与新增偏好缺值时使用默认值，需要重新设置现有开发配置；旧文件不读取、不删除，遗留 Keychain 条目不访问、不清理。已有语言、静默启动、测试 URL 等独立偏好及服务器资料保持原状。监听读取失败会阻断正常启动，包括静默启动，并显示只含“重置监听配置”的说明性 alert。用户确认后创建新监听主密钥并原子保存默认配置，默认关闭局域网监听。重置成功前保留原文件及已有后台代理和系统代理；成功后按默认配置与原有开关意图收敛。不迁移旧 proxy-listening.enc 或 proxy-listening.json，不读取或清理旧逐项 Keychain 凭据；发现旧文件时同样提示确认重置。设计见 ADR-0034、ADR-0040、ADR-0041、ADR-0042 和 ADR-0050。
应用支持目录
文件根目录为 ~/Library/Application Support/ShadowsocksX-NG2/，按生命周期分类：
| 子目录 | 文件与用途 |
|---|---|
configuration/ |
catalog.age、proxy-listening.age、activation.json、custom-rules.json、plugins.json，由 GUI 管理的持久资料 |
runtime/ |
监管资料、运行回执、失败记录、PID、稳定链接，以及代次命名的配置、GUI 私有意图摘要、认证与 ACL 文件 |
logs/ |
agent.log，停止后台代理后保留 |
runtime-generation、runtime.lock、agent.lock 位于 runtime/，停止服务仍保留。不能把停止操作实现为删除整个运行目录。目录权限为 0700，普通文件权限为 0600；运行配置和认证文件仍可能包含明文秘密。UserDefaults、Keychain、LaunchAgent plist 及 bundle 内规则与插件继续使用各自的位置。
此次布局调整不提供自动迁移。旧根目录文件不读取、不移动、不删除，包括初版 silent-launch.json；已保存的 UserDefaults 偏好不变。开发环境切换前，退出 GUI 并停止旧 Agent 与 sslocal，确认进程退出后，将需要保留的上述五份 GUI 文件原样搬到 configuration/，不要搬移运行产物。当前 age 文件可沿用同一用户对应 service 中的 Keychain identity；历史自研 .enc 文件不迁移，不能只改扩展名继续使用。不应只复制密文到另一台机器并假定能够解密。设置目录权限为 0700、文件权限为 0600，再启动新构建，由新路径重新派生运行产物。未搬移配置时，新目录按首次使用初始化；不会从旧根目录补读。新目录内旧格式文件的拒绝规则仍保留。
路径规则集中在 ApplicationSupportPaths 与 RuntimePaths。Agent 的测试覆盖中，SSXNG_CONTRACT_PATH 优先于 SSXNG_RUNTIME_DIR，同一部署全部路径由该契约所在目录派生；仅设置运行目录时使用标准配置链接名。SSXNG_LOG_PATH 可独立指定日志位置。指定测试契约或运行目录且未指定日志时，日志留在被覆盖的运行目录，避免测试写入生产日志。