Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apple/ClashClient/Shared/ConfigResourceStore.swift
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,8 @@ final class ConfigResourceStore {
activeDirectoryURL.appendingPathComponent(Name.compatibilityConfiguration)
}

var workingDirectoryURL: URL { workingURL }

init(
containerURL: URL,
maximumConfigurationBytes: Int = ConfigResourceStore.defaultMaximumConfigurationBytes,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,11 @@ final class ActiveRevisionMigrator {
profileID: currentPointer.profileID,
revision: currentPointer.revision
)
if validates(active) {
let inputsChanged = ProfileInputsStamp.inputsChanged(
currentPointer,
workingDirectory: store.workingDirectoryURL
)
if !inputsChanged, validates(active) {
return StartupConfigurationPreparation(
configuration: active,
recovery: .current
Expand All @@ -112,8 +116,12 @@ final class ActiveRevisionMigrator {
}
expectedPointer = rebuiltPointer
} catch {


if validates(active) {
return StartupConfigurationPreparation(
configuration: active,
recovery: .current
)
}
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3469,6 +3469,7 @@ final class ProfileActivationCoordinator {
}
PublishedSourceLedger.record(published, digest: sourceDigest?.ledger)
PublishedRulesAsWritten.record(published, section: rulesAsWritten, workingDirectory: coreHomeDir)
ProfileInputsStamp.record(published, profile: profile, workingDirectory: coreHomeDir)



Expand Down
77 changes: 77 additions & 0 deletions apple/ClashClient/Sources/ConfigStore/ProfileInputsStamp.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
import CryptoKit
import Foundation

enum ProfileInputsStamp {
static let fileName = "published-inputs.json"
private static let schemaVersion = 1
private static let storeDirectoryName = "store"

private struct Record: Codable {
let schemaVersion: Int
let profileID: String
let revision: String
let inputs: String
}

private struct Inputs: Encodable {
let appendRules: [String]
let prependRules: Bool
let legacyRuntimePatchJSON: String?
}

private static func url(workingDirectory: URL) -> URL {
workingDirectory
.appendingPathComponent(storeDirectoryName, isDirectory: true)
.appendingPathComponent(fileName)
}

private static func digest(of profile: Profile) -> String {
let encoder = JSONEncoder()
encoder.outputFormatting = [.sortedKeys]
guard let data = try? encoder.encode(Inputs(
appendRules: profile.override.appendRules,
prependRules: profile.override.prependRules,
legacyRuntimePatchJSON: profile.legacyRuntimePatchJSON
)) else { return "" }
return SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
}

static func record(_ pointer: ActiveConfigurationPointer, profile: Profile, workingDirectory: URL) {
let file = url(workingDirectory: workingDirectory)
let record = Record(
schemaVersion: schemaVersion,
profileID: pointer.profileID,
revision: pointer.revision,
inputs: digest(of: profile)
)
guard let data = try? JSONEncoder().encode(record) else { return }
try? FileManager.default.createDirectory(
at: file.deletingLastPathComponent(),
withIntermediateDirectories: true
)
try? data.write(to: file, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])
}

private static func read(workingDirectory: URL) -> Record? {
guard let data = try? Data(contentsOf: url(workingDirectory: workingDirectory)) else { return nil }
return try? JSONDecoder().decode(Record.self, from: data)
}

static func inputsChanged(_ pointer: ActiveConfigurationPointer, workingDirectory: URL) -> Bool {
guard let profile = storedProfile(pointer.profileID, workingDirectory: workingDirectory) else {
return false
}
guard let record = read(workingDirectory: workingDirectory) else { return true }
return record.schemaVersion != schemaVersion
|| record.profileID != pointer.profileID
|| record.revision != pointer.revision
|| record.inputs != digest(of: profile)
}

private static func storedProfile(_ profileID: String, workingDirectory: URL) -> Profile? {
let file = workingDirectory
.appendingPathComponent(storeDirectoryName, isDirectory: true)
.appendingPathComponent("profiles.json")
return ProfileStore(fileURL: file).load().first { $0.id == profileID }
}
}
40 changes: 35 additions & 5 deletions cli/HELP.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: clash-cli
description: 通过 Clash App 内置的 clash-cli,在 Mac 终端里实时监控和控制 Clash App(本机 Mac,或局域网里的 iPhone / iPad / Apple TV)。支持状态/连接/流量/规则查询、规则命中分析、节点与策略组切换、节点测速、DNS 查询。当用户提到 Clash App、切换节点、查看连接、实时流量、规则匹配、节点测速、外部控制器时使用。
description: 通过 Clash App 内置的 clash-cli,在 Mac 终端里实时监控和控制 Clash App(本机 Mac,或局域网里的 iPhone / iPad / Apple TV)。支持状态/连接/流量/规则查询、规则命中分析、节点与策略组切换、节点测速、DNS 查询,以及 App 配置里追加规则与 DNS 策略的读写。当用户提到 Clash App、切换节点、查看连接、实时流量、规则匹配、节点测速、外部控制器、追加规则、nameserver-policy 时使用。
---

# Clash App 控制器(Clash App 内置的 clash-cli)
Expand Down Expand Up @@ -60,7 +60,9 @@ clash-cli status
| `clash-cli traffic [秒]` | 实时流量(瞬时速率 + 累计) |
| `clash-cli connections [N]` | 活跃连接列表(host → 策略链 → 命中规则 → 上下行),默认前 20 |
| `clash-cli configs` | 当前运行配置(端口/tun/dns 等),只输出 JSON,可直接接 `jq`;`--json` 是控制器原样的回答。端口实际监听在哪看 `clash-cli status`:port、socks-port、mixed-port、redir-port、tproxy-port 先看 `allow-lan`,关着时只在 127.0.0.1 上,`bind-address` 写什么都不起作用;开着时才按 `bind-address`(没写就是 `*`),再由 `lan-allowed-ips`/`lan-disallowed-ips` 筛设备。App 里「允许局域网连接」关着时会把 `allow-lan` 改成 false。`listeners:` 里自己写的监听不归它管 |
| `clash-cli rules [N]` | 规则列表(默认前 10,0 = 全部) |
| `clash-cli rules [N]` | 规则列表(默认前 10,0 = 全部);这是运行态,改配置见 §4 的配置库 |
| `clash-cli profiles` | App 里的配置列表(`*` 当前),带追加规则条数;`--json` 是控制器原样的回答 |
| `clash-cli dns policy [--profile <id\|名称>]` | 这份配置的 DNS 策略:`nameserver-policy` 与 `fake-ip-filter`(缺省当前配置) |
| `clash-cli rule match <域名\|IP\|URL>` | **规则命中分析**:这条连接会命中哪条规则、走哪条链 |
| `clash-cli provider list` | 节点集与规则集 |
| `clash-cli dns query <域名> [type]` | 走内核 DNS 查询,返回 Answer 数组 |
Expand Down Expand Up @@ -98,7 +100,7 @@ clash-cli status
## 4. 影响边界(写操作)

- **写操作**:`proxy set`、`mode`、`group unfix`、`group test`、`provider update`、`conn close <id|all>`、`flush`
会改变运行状态,执行前先确认目标存在(`proxy get`、`proxies`、`connections`)。
会改变运行状态;`rules append|remove`、`dns policy set|clear` 会改配置库(见本节末尾)。执行前先确认目标存在(`proxy get`、`proxies`、`connections`、`profiles`)。
每次写操作前,人读输出会先打印要改的是哪台设备、哪个内核版本。
- `provider update` 让隧道向服务器检查一次,按结果报:已更新(条数前后对比)、没有变化、打开 Clash 后生效(新内容已取到,App 打开后用上;原因在 --json 的 pendingReason 里);
检查失败时报集合名和内核给的原因(原样),退出码 1。检查失败或控制器报错时退出码非 0(隧道还在检查、等不及回答的 504 也算控制器报错)。
Expand All @@ -108,6 +110,34 @@ clash-cli status
- **`reload`、`check` 不可用**:配置由 Clash App 管理(组合、切换、检查都在 App 里),这两个命令返回退出码 5。
要换配置、更新订阅或检查配置文件,请在 App 里操作。

### 配置库:`rules append|remove`、`dns policy`

这一组命令改的是 App 的**配置库**(`~/Library/Group Containers/group.com.hako.network/working/store/profiles.json` 里的
`override.appendRules`、`override.prependRules`,以及 `legacyRuntimePatchJSON` 里的 `dns.nameserver-policy`、`dns.fake-ip-filter`),
**不是现在的运行态**:改动**下次连接生效**(现在连着的连接仍按旧规则),也不重建派生产物(那是 App 在连接时做的)。
内核没给 `app-store-v1` 能力时,这些命令退出码 5,并说明「还不支持 App 配置读写(app-store-v1)」。

```bash
clash-cli profiles # 列配置,* 是当前;--json 拿原样回答
clash-cli rules append 'DOMAIN-SUFFIX,corp.example.com,DIRECT' \
'IP-CIDR,10.0.0.0/8,DIRECT,no-resolve'
clash-cli rules remove 'IP-CIDR,10.0.0.0/8,DIRECT,no-resolve'
clash-cli rules append 'DOMAIN,foo.example.com,PROXY' --profile XSUS # 指定配置(id 或名称)
clash-cli dns policy # 看 nameserver-policy / fake-ip-filter
clash-cli dns policy set '+.corp.example.com=10.78.226.116,10.78.226.117'
clash-cli dns policy clear # 清空 nameserver-policy
clash-cli dns policy clear --fake-ip-filter
```

- `--profile` 缺省是当前配置(`profiles` 里带 `*` 的那个),也可以给 id 或名称;有同名配置时要求用 id。
- `rules append` 合并写入并去重:本来就在的规则跳过,输出里说明跳过几条;`rules remove` 只删完全一致的规则。
去重后没有变化时不写入,只报现有条数。
- `dns policy set` 按域名合并:同一个域名再设一次会整体替换它的地址列表;要清空某个域名就用 `dns policy clear`。
`dns policy clear` 默认只清 `nameserver-policy`,加 `--fake-ip-filter` 时只清 `fake-ip-filter`(两者互斥,各跑一次)。
- 写入由控制器原子落盘,并保留配置里其它字段(`prependRules`、`tun`、`sniffer`、未知字段)不被改动。
- 校验在控制器那侧:每条规则 1..512 字节、不含换行、最多 5000 条;域名非空且 ≤253 字节,地址是合法 IP 或
`https://`/`tls://`/`quic://`/`h3://`/`dhcp://` 前缀且 ≤512 字节。非法时控制器回 400、不落盘,CLI 原样转述(退出码 1)。

## 5. 环境与安全注意事项

- 拿到密钥的人可以完全控制 Clash(模式、局域网共享、选节点、断连接、清缓存)。不要把密钥贴进公开的地方;
Expand All @@ -117,8 +147,8 @@ clash-cli status
- 全局选项(放在命令前后都行;与环境变量同时给出时用选项的值):`-u` / `--url`、`--secret`、`--secret-stdin`、
`--fingerprint`、`--timeout`、`--json`。`CLASH_TIMEOUT` 写得不合法时无论给不给 `--timeout` 都报退出码 2。
- 切换节点时节点名必须与策略组成员**精确匹配**(含空格/emoji/特殊字符,如「🇭🇰香港trojan1」)。
- 退出码:0 成功;1 控制器报错;2 用法;3 连不上;4 密钥被拒;5 不是 Clash App 的控制器或不支持(含 `reload`、`check`);
6 证书指纹不符或未确认。
- 退出码:0 成功;1 控制器报错;2 用法;3 连不上;4 密钥被拒;5 不是 Clash App 的控制器或不支持(含 `reload`、`check`,
以及内核没有 `app-store-v1` 时的配置读写);6 证书指纹不符或未确认。
- 已知指纹记在 `~/.config/clash-cli/known_hosts`(App 内置版在沙盒容器里:
`~/Library/Containers/<App 标识>.clash-cli/Data/.config/clash-cli/known_hosts`)。

Expand Down
Loading