diff --git a/design/server/openapi.yaml b/design/server/openapi.yaml index 0eed1b8..89bb92d 100644 --- a/design/server/openapi.yaml +++ b/design/server/openapi.yaml @@ -244,10 +244,18 @@ components: description: 国内域名/IP 直连 lan_direct: type: boolean - description: 局域网直连 + readOnly: true + description: >- + reserved/always-on:局域网直连由系统层恒渲染(route_exclude_address + + 固定 LAN 直连规则),渲染器不读此开关,当前始终生效;字段保留供未来扩展 + per-user 关闭,目前无实际效果。 private_via_tunnel: type: boolean - description: 私有服务域名强制走隧道(家庭内网穿透场景) + readOnly: true + description: >- + reserved/always-on:配置了 PANGOLIN_PRIVATE_SPLIT_DOMAINS 时,这些私有 + 服务域名恒强制走隧道,渲染器不读此开关,当前始终生效;字段保留供未来扩展 + per-user 关闭,目前无实际效果。 RoutingProfile: type: object @@ -267,6 +275,24 @@ components: type: string enum: [proxy, direct] + RoutingProfileResponse: + description: GET /me/routing 响应体:档案字段 + 只读的系统强制域名清单 + allOf: + - $ref: '#/components/schemas/RoutingProfile' + - type: object + required: [system_locked_domains] + properties: + system_locked_domains: + type: array + readOnly: true + items: + type: string + description: >- + 系统强制走隧道的私有服务域名(PANGOLIN_PRIVATE_SPLIT_DOMAINS)。 + 用户对这些域名的自定义规则会静默失效;仅供客户端提示用户,不可写入 + (POST 请求体中出现该字段会被忽略,不会持久化)。 + example: [nas.example.com] + RoutingValidationError: type: object required: [code, message_zh, message_en, errors] @@ -500,11 +526,11 @@ paths: summary: 获取当前用户的分流配置(可配置分流;未自定义时返回默认档案) responses: '200': - description: 分流档案 + description: 分流档案(含只读 system_locked_domains) content: application/json: schema: - $ref: '#/components/schemas/RoutingProfile' + $ref: '#/components/schemas/RoutingProfileResponse' '401': description: 未认证 content: diff --git a/server/api/openapi.yaml b/server/api/openapi.yaml index ff0b689..4ba922d 100644 --- a/server/api/openapi.yaml +++ b/server/api/openapi.yaml @@ -259,11 +259,11 @@ paths: tags: [Account] responses: "200": - description: 分流档案 + description: 分流档案(含只读 system_locked_domains) content: application/json: schema: - $ref: "#/components/schemas/RoutingProfile" + $ref: "#/components/schemas/RoutingProfileResponse" "401": $ref: "#/components/responses/Unauthorized" "500": @@ -1209,10 +1209,18 @@ components: description: 国内域名/IP 直连 lan_direct: type: boolean - description: 局域网直连 + readOnly: true + description: >- + reserved/always-on:局域网直连由系统层恒渲染(route_exclude_address + + 固定 LAN 直连规则),渲染器不读此开关,当前始终生效;字段保留供未来扩展 + per-user 关闭,目前无实际效果。 private_via_tunnel: type: boolean - description: 私有服务域名强制走隧道(家庭内网穿透场景) + readOnly: true + description: >- + reserved/always-on:配置了 PANGOLIN_PRIVATE_SPLIT_DOMAINS 时,这些私有 + 服务域名恒强制走隧道,渲染器不读此开关,当前始终生效;字段保留供未来扩展 + per-user 关闭,目前无实际效果。 RoutingProfile: type: object @@ -1232,6 +1240,24 @@ components: type: string enum: [proxy, direct] + RoutingProfileResponse: + description: GET /me/routing 响应体:档案字段 + 只读的系统强制域名清单 + allOf: + - $ref: "#/components/schemas/RoutingProfile" + - type: object + required: [system_locked_domains] + properties: + system_locked_domains: + type: array + readOnly: true + items: + type: string + description: >- + 系统强制走隧道的私有服务域名(PANGOLIN_PRIVATE_SPLIT_DOMAINS)。 + 用户对这些域名的自定义规则会静默失效;仅供客户端提示用户,不可写入 + (POST 请求体中出现该字段会被忽略,不会持久化)。 + example: [nas.example.com] + RoutingValidationError: type: object required: [code, message_zh, message_en, errors] diff --git a/server/cmd/server/main.go b/server/cmd/server/main.go index 0d12f8c..036951d 100644 --- a/server/cmd/server/main.go +++ b/server/cmd/server/main.go @@ -408,7 +408,18 @@ func mountV1(r chi.Router, sqlDB *sql.DB, rdb *redis.Client, nodeSvc *nodes.Serv accountAPI := httpapi.NewAccountAPI(sqlDB) // ── Routing profile (可配置分流) ─────────────────────────────────────────── - routingAPI := httpapi.NewRoutingAPI(routing.NewStore(sqlDB)) + // 私有服务域名分流(家庭内网穿透,如 nas/git/win.yanmeiai.com):逗号分隔; + // 这些域名用系统 DNS 解析、在外强制走隧道(排在国内分流前)。用户对这些域名的 + // 自定义规则会静默失效——同一份 slice 注入 RoutingAPI,GET /v1/me/routing + // 附带 system_locked_domains 供客户端提示,以及 NodeAPI(渲染 sing-box 配置)。 + var privateSplitDomains []string + for _, d := range strings.Split(os.Getenv("PANGOLIN_PRIVATE_SPLIT_DOMAINS"), ",") { + if d = strings.TrimSpace(d); d != "" { + privateSplitDomains = append(privateSplitDomains, d) + } + } + routingStore := routing.NewStore(sqlDB) + routingAPI := httpapi.NewRoutingAPI(routingStore, privateSplitDomains) // ── Nodes + Connect ─────────────────────────────────────────────────────── var nodeAPI *httpapi.NodeAPI @@ -423,15 +434,7 @@ func mountV1(r chi.Router, sqlDB *sql.DB, rdb *redis.Client, nodeSvc *nodes.Serv slog.Warn("PANGOLIN_PUBLIC_URL 未设置:国内分流(split_cn)将被静默跳过,客户端全量走隧道。" + "如需国内直连,设为控制面对外公网基址(如 http://<公网IP>:8080)") } - // 私有服务域名分流(家庭内网穿透,如 nas/git/win.yanmeiai.com): - // 逗号分隔;这些域名用系统 DNS 解析、在外强制走隧道(排在国内分流前)。 - var privateSplitDomains []string - for _, d := range strings.Split(os.Getenv("PANGOLIN_PRIVATE_SPLIT_DOMAINS"), ",") { - if d = strings.TrimSpace(d); d != "" { - privateSplitDomains = append(privateSplitDomains, d) - } - } - nodeAPI = httpapi.NewNodeAPI(nodeStore, nodeSvc.Hub(), nodeSvc.Load(), os.Getenv("NODE_DERIVE_KEY"), publicURL, privateSplitDomains, routing.NewStore(sqlDB)) + nodeAPI = httpapi.NewNodeAPI(nodeStore, nodeSvc.Hub(), nodeSvc.Load(), os.Getenv("NODE_DERIVE_KEY"), publicURL, privateSplitDomains, routingStore) } // 国内分流(#5)的 rule-set 静态服务:GET /v1/rules/{name}.srs(自托管, diff --git a/server/internal/httpapi/clientconfig.go b/server/internal/httpapi/clientconfig.go index 0db1740..7bc0020 100644 --- a/server/internal/httpapi/clientconfig.go +++ b/server/internal/httpapi/clientconfig.go @@ -270,9 +270,15 @@ func BuildClientConfig(node *nodes.NodeRow, dpUUID, deriveKey string, opts Clien if len(extraExclude) > 0 { // IP 直连真生效:并入 TUN 入站的 route_exclude_address(auto_route 层排除, // 见 tunIn 构造处注释——单靠 route.rules 的 ip_cidr→direct 在 macOS - // strict_route 下不生效)。与既有 LAN 网段去重合并。 - exclude := []string{"192.168.0.0/16", "10.0.0.0/8"} - seen := map[string]bool{"192.168.0.0/16": true, "10.0.0.0/8": true} + // strict_route 下不生效)。单源读 tunIn 现有种子(不重复硬编码 LAN 网段; + // 其为 192.168+10,与上面 route.rules 的 LAN 直连 4 段有意不同——不能改成 + // LAN 全集,否则会漏排除/多排除),与 extraExclude 去重合并、写回。 + base, _ := tunIn["route_exclude_address"].([]string) + exclude := append([]string{}, base...) + seen := make(map[string]bool, len(base)) + for _, e := range base { + seen[e] = true + } for _, e := range extraExclude { if !seen[e] { seen[e] = true diff --git a/server/internal/httpapi/nodes_connect_test.go b/server/internal/httpapi/nodes_connect_test.go index ead8e0c..bd96d78 100644 --- a/server/internal/httpapi/nodes_connect_test.go +++ b/server/internal/httpapi/nodes_connect_test.go @@ -64,6 +64,19 @@ func openRoutingDB(t *testing.T) *sql.DB { return db } +// seedConnectUser inserts a minimal users row so routing_profiles inserts +// (which now declare FOREIGN KEY (user_id) REFERENCES users(id)) satisfy the +// constraint — this DB opens with _pragma=foreign_keys(1) (internal/db/db.go), +// so SQLite does enforce it, unlike a bare default SQLite connection. +func seedConnectUser(t *testing.T, db *sql.DB, id int64) { + t.Helper() + uuid := "u-connect" + if _, err := db.Exec(`INSERT INTO users (id,uuid,email,pw_hash,dp_uuid,status,created_at) + VALUES (?,?,?, 'x','dp-'||?, 'active', ?)`, id, uuid, uuid+"@x", uuid, time.Now().UTC()); err != nil { + t.Fatal(err) + } +} + // newOnlineHub returns a real *nodes.Hub (backed by miniredis) with nodeUUID // registered online, so ConnectNode's a.hub.IsOnline(...) gate passes and // Push(...) succeeds without a real Redis deployment. @@ -98,6 +111,7 @@ func TestConnectNode_ReadsRoutingProfile(t *testing.T) { const uid = int64(42) db := openRoutingDB(t) + seedConnectUser(t, db, uid) rst := routing.NewStore(db) p := routing.Default() p.Rules = []routing.Rule{ @@ -167,6 +181,7 @@ func TestConnectNode_RoutingStoreErr_FailsSafe(t *testing.T) { const uid = int64(44) db := openRoutingDB(t) + seedConnectUser(t, db, uid) // 写入一条无法反序列化的 profile_json,模拟 Get 出错。 if _, err := db.Exec(`INSERT INTO routing_profiles (user_id, profile_json, updated_at) VALUES (?,?,?)`, uid, "{not-json", time.Now().UTC()); err != nil { diff --git a/server/internal/httpapi/routing.go b/server/internal/httpapi/routing.go index 743125c..91e3fac 100644 --- a/server/internal/httpapi/routing.go +++ b/server/internal/httpapi/routing.go @@ -14,10 +14,28 @@ import ( // user hasn't customized one yet; POST validates and upserts. type RoutingAPI struct { store *routing.Store + // lockedDomains are the system-forced-tunnel private-service domains + // (PANGOLIN_PRIVATE_SPLIT_DOMAINS, same slice injected into NodeAPI) — + // read-only, surfaced to GET so clients can warn users that rules against + // these domains silently have no effect. Never written to the persisted + // Profile. + lockedDomains []string } // NewRoutingAPI creates a RoutingAPI backed by the given routing.Store. -func NewRoutingAPI(store *routing.Store) *RoutingAPI { return &RoutingAPI{store: store} } +// lockedDomains is the system-forced private-service domain list (may be nil). +func NewRoutingAPI(store *routing.Store, lockedDomains []string) *RoutingAPI { + return &RoutingAPI{store: store, lockedDomains: lockedDomains} +} + +// profileResponse wraps routing.Profile for GET /v1/me/routing, adding the +// read-only system_locked_domains list. It deliberately lives here — not on +// routing.Profile itself — so the field can never leak into the writable +// Profile contract that SaveProfile decodes POST bodies into. +type profileResponse struct { + *routing.Profile + SystemLockedDomains []string `json:"system_locked_domains"` +} // GetProfile handles GET /v1/me/routing. func (a *RoutingAPI) GetProfile(w http.ResponseWriter, r *http.Request) { @@ -34,7 +52,11 @@ func (a *RoutingAPI) GetProfile(w http.ResponseWriter, r *http.Request) { if p == nil { p = routing.Default() } - writeJSON(w, http.StatusOK, p) + locked := a.lockedDomains + if locked == nil { + locked = []string{} + } + writeJSON(w, http.StatusOK, profileResponse{Profile: p, SystemLockedDomains: locked}) } // SaveProfile handles POST /v1/me/routing. On validation failure it returns diff --git a/server/internal/httpapi/routing_test.go b/server/internal/httpapi/routing_test.go index c01d6da..a385ead 100644 --- a/server/internal/httpapi/routing_test.go +++ b/server/internal/httpapi/routing_test.go @@ -65,7 +65,7 @@ func doAuthReq(t *testing.T, method, target string, body *strings.Reader, uid in func TestRoutingGetDefaultThenSave(t *testing.T) { db := openRoutingTestDB(t) seedRoutingUser(t, db, 7) - api := NewRoutingAPI(routing.NewStore(db)) + api := NewRoutingAPI(routing.NewStore(db), nil) // GET 无档案 → 200 + Default rr := doAuthReq(t, http.MethodGet, "/v1/me/routing", nil, 7, api.GetProfile) @@ -120,7 +120,7 @@ func TestRoutingGetDefaultThenSave(t *testing.T) { func TestRoutingGetUnauthorized(t *testing.T) { db := openRoutingTestDB(t) - api := NewRoutingAPI(routing.NewStore(db)) + api := NewRoutingAPI(routing.NewStore(db), nil) req := httptest.NewRequest(http.MethodGet, "/v1/me/routing", nil) rr := httptest.NewRecorder() api.GetProfile(rr, req) @@ -128,3 +128,82 @@ func TestRoutingGetUnauthorized(t *testing.T) { t.Fatalf("expected 401, got %d", rr.Code) } } + +// TestRoutingGetExposesSystemLockedDomains: GET must surface the injected +// lockedDomains list under system_locked_domains, without it ever ending up +// as part of routing.Profile's own field set. +func TestRoutingGetExposesSystemLockedDomains(t *testing.T) { + db := openRoutingTestDB(t) + seedRoutingUser(t, db, 8) + api := NewRoutingAPI(routing.NewStore(db), []string{"nas.x.com"}) + + rr := doAuthReq(t, http.MethodGet, "/v1/me/routing", nil, 8, api.GetProfile) + if rr.Code != 200 { + t.Fatalf("GET code %d", rr.Code) + } + var resp struct { + SystemLockedDomains []string `json:"system_locked_domains"` + } + if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil { + t.Fatalf("unmarshal: %v", err) + } + if len(resp.SystemLockedDomains) != 1 || resp.SystemLockedDomains[0] != "nas.x.com" { + t.Fatalf("want system_locked_domains=[nas.x.com], got %v", resp.SystemLockedDomains) + } +} + +// TestRoutingGetSystemLockedDomainsNilBecomesEmptyArray: a nil lockedDomains +// slice (no PANGOLIN_PRIVATE_SPLIT_DOMAINS configured) must serialize as +// `[]`, not `null` — clients shouldn't need a nil-check. +func TestRoutingGetSystemLockedDomainsNilBecomesEmptyArray(t *testing.T) { + db := openRoutingTestDB(t) + seedRoutingUser(t, db, 9) + api := NewRoutingAPI(routing.NewStore(db), nil) + + rr := doAuthReq(t, http.MethodGet, "/v1/me/routing", nil, 9, api.GetProfile) + if rr.Code != 200 { + t.Fatalf("GET code %d", rr.Code) + } + var raw map[string]json.RawMessage + if err := json.Unmarshal(rr.Body.Bytes(), &raw); err != nil { + t.Fatalf("unmarshal: %v", err) + } + if got := string(raw["system_locked_domains"]); got != "[]" { + t.Fatalf("want system_locked_domains=`[]`, got %s", got) + } +} + +// TestRoutingSaveIgnoresSystemLockedDomains: a client POSTing a body that +// includes system_locked_domains must not have it persisted — SaveProfile +// decodes straight into routing.Profile, which has no such field, so the +// key is silently dropped. Verify against the raw stored row (not the GET +// response, which always injects it from a.lockedDomains regardless of what +// was ever saved). +func TestRoutingSaveIgnoresSystemLockedDomains(t *testing.T) { + db := openRoutingTestDB(t) + seedRoutingUser(t, db, 10) + store := routing.NewStore(db) + api := NewRoutingAPI(store, []string{"nas.x.com"}) + + body := `{"mode":"rule","builtin":{"china_direct":true,"lan_direct":true,"private_via_tunnel":true},` + + `"rules":[],"final":"proxy","system_locked_domains":["evil.attacker.com"]}` + rr := doAuthReq(t, http.MethodPost, "/v1/me/routing", strings.NewReader(body), 10, api.SaveProfile) + if rr.Code != 200 { + t.Fatalf("POST code %d body %s", rr.Code, rr.Body) + } + + stored, err := store.Get(context.Background(), 10) + if err != nil { + t.Fatal(err) + } + if stored == nil { + t.Fatal("expected a persisted profile") + } + raw, err := json.Marshal(stored) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(raw), "system_locked_domains") || strings.Contains(string(raw), "evil.attacker.com") { + t.Fatalf("system_locked_domains must never be persisted, got stored profile JSON: %s", raw) + } +} diff --git a/server/internal/routing/profile.go b/server/internal/routing/profile.go index 744b7ec..a490b65 100644 --- a/server/internal/routing/profile.go +++ b/server/internal/routing/profile.go @@ -21,8 +21,17 @@ type Rule struct { // Builtin toggles the built-in routing behaviors that previously were // hardcoded into the server's sing-box config rendering. type Builtin struct { - ChinaDirect bool `json:"china_direct"` - LanDirect bool `json:"lan_direct"` + ChinaDirect bool `json:"china_direct"` + // LanDirect is reserved/always-on: the system layer (route_exclude_address + // + the hardcoded LAN direct rule in clientconfig.go) renders unconditionally + // regardless of this flag's value — the renderer does not read it. Kept in + // the wire contract for a possible future per-user opt-out; today it has no + // effect on rendering. + LanDirect bool `json:"lan_direct"` + // PrivateViaTunnel is reserved/always-on: when PANGOLIN_PRIVATE_SPLIT_DOMAINS + // is configured, those domains are always force-routed through the tunnel — + // the renderer does not read this flag. Kept in the wire contract for a + // possible future per-user opt-out; today it has no effect on rendering. PrivateViaTunnel bool `json:"private_via_tunnel"` } @@ -64,11 +73,11 @@ var geoWhitelist = map[string]bool{"cn": true} // geoip/geosite 仅自托管 cn // Validate checks the profile against the type/action whitelist, CIDR // syntax, the geo set whitelist, and the rule count cap. It returns an empty -// (nil) slice when the profile is valid; every violation is reported -// independently (no short-circuiting) so callers can surface all errors at -// once. +// (non-nil) slice when the profile is valid — so JSON encoding produces `[]` +// rather than `null` — and every violation is reported independently (no +// short-circuiting) so callers can surface all errors at once. func (p *Profile) Validate() []FieldError { - var errs []FieldError + errs := []FieldError{} if p.Mode != "rule" && p.Mode != "global" && p.Mode != "direct" { errs = append(errs, FieldError{-1, "mode", "must be rule|global|direct"}) } @@ -102,14 +111,20 @@ func (p *Profile) Validate() []FieldError { return errs } +// dedupKey identifies a rule for Normalize's de-duplication. Using a struct +// (rather than string-concatenating Type+Value+Action with a separator) +// avoids false-collision when a value itself contains the separator +// character. +type dedupKey struct{ Type, Value, Action string } + // Normalize trims rule values and de-duplicates rules by (type, value, // action), keeping the first occurrence's position (and its Note/Enabled). func (p *Profile) Normalize() { - seen := map[string]bool{} + seen := map[dedupKey]bool{} out := p.Rules[:0] for _, r := range p.Rules { r.Value = strings.TrimSpace(r.Value) - k := r.Type + "|" + r.Value + "|" + r.Action + k := dedupKey{r.Type, r.Value, r.Action} if seen[k] { continue } diff --git a/server/internal/routing/profile_test.go b/server/internal/routing/profile_test.go index 22d3ac2..32040ac 100644 --- a/server/internal/routing/profile_test.go +++ b/server/internal/routing/profile_test.go @@ -1,13 +1,32 @@ package routing -import "testing" +import ( + "encoding/json" + "testing" +) + +// TestValidateEmptyErrorsSerializeAsArray guards the JSON shape API clients +// depend on: a valid profile's Validate() must marshal to `[]`, not `null`. +func TestValidateEmptyErrorsSerializeAsArray(t *testing.T) { + raw, err := json.Marshal(Default().Validate()) + if err != nil { + t.Fatal(err) + } + if string(raw) != "[]" { + t.Fatalf("want `[]`, got %s", raw) + } +} func TestValidate(t *testing.T) { ok := Default() ok.Rules = []Rule{{Type: "domain_suffix", Value: "example.com", Action: "direct", Enabled: true}} - if e := ok.Validate(); len(e) != 0 { + e := ok.Validate() + if len(e) != 0 { t.Fatalf("valid profile got errors %v", e) } + if e == nil { + t.Fatal("Validate must return a non-nil empty slice (serializes to [] not null)") + } bad := Default() bad.Mode = "weird" // 非法 mode @@ -48,3 +67,19 @@ func TestNormalizeDedupAndTrim(t *testing.T) { t.Fatalf("want first-occurrence order preserved, got %v", p.Rules) } } + +// TestNormalizeDedupNoSeparatorCollision guards against the historical +// string-concatenation dedup key ("type|value|action"): two distinct rules +// whose Value contains "|" could concatenate to the same string even though +// (type, value, action) differ. The struct-keyed dedup must tell them apart. +func TestNormalizeDedupNoSeparatorCollision(t *testing.T) { + p := Default() + p.Rules = []Rule{ + {Type: "domain", Value: "a|b", Action: "proxy", Enabled: true}, + {Type: "domain", Value: "a", Action: "b|proxy", Enabled: true}, + } + p.Normalize() + if len(p.Rules) != 2 { + t.Fatalf("want 2 distinct rules preserved (no false collision), got %d: %v", len(p.Rules), p.Rules) + } +} diff --git a/server/internal/routing/store_sqlite_test.go b/server/internal/routing/store_sqlite_test.go index f479504..8e97596 100644 --- a/server/internal/routing/store_sqlite_test.go +++ b/server/internal/routing/store_sqlite_test.go @@ -32,6 +32,27 @@ func seedU(t *testing.T, db *sql.DB, id int64, uuid string) { } } +// TestSQLiteRoutingStoreGetNoProfileRow isolates the "queried the DB, found +// no row" path from TestSQLiteRoutingStoreUpsertGet's combined +// empty→upsert→overwrite flow: a store backed by a real (non-nil) *sql.DB, +// with the user seeded but no routing_profiles row for them, must return +// (nil, nil) — not an error — via the sql.ErrNoRows branch in Store.Get. +func TestSQLiteRoutingStoreGetNoProfileRow(t *testing.T) { + db := openDB(t) + seedU(t, db, 2, "u2") + st := NewStore(db) + if st == nil { + t.Fatal("NewStore returned nil") + } + got, err := st.Get(context.Background(), 2) + if err != nil { + t.Fatalf("want nil error for no-rows, got %v", err) + } + if got != nil { + t.Fatalf("want nil profile for seeded user with no profile row, got %+v", got) + } +} + func TestSQLiteRoutingStoreUpsertGet(t *testing.T) { db := openDB(t) // 内存库 + MigrateUp(sqlite) seedU(t, db, 1, "u1") diff --git a/server/migrations/sqlite/000028_routing_profiles.up.sql b/server/migrations/sqlite/000028_routing_profiles.up.sql index 2510345..86c27f7 100644 --- a/server/migrations/sqlite/000028_routing_profiles.up.sql +++ b/server/migrations/sqlite/000028_routing_profiles.up.sql @@ -1,5 +1,6 @@ CREATE TABLE routing_profiles ( user_id INTEGER NOT NULL PRIMARY KEY, profile_json TEXT NOT NULL, - updated_at DATETIME NOT NULL + updated_at DATETIME NOT NULL, + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE );