Qiu Yuzhou
f9e95474e5
Replace the custom encrypted container with AgeSwift 0.1.0 so standard age tools can inspect sensitive configuration independently of the app. Use independent Keychain X25519 identities for catalog.age and proxy-listening.age. Preserve atomic commits and confirmed recovery; reject historical NG2 formats without migration or cleanup.
9.3 KiB
订阅、插件与监听配置
订阅资料
订阅可在 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 可独立指定日志位置。指定测试契约或运行目录且未指定日志时，日志留在被覆盖的运行目录，避免测试写入生产日志。