refactor(routing): 暴露 system_locked_domains + 服务端 follow-up 清理(FK/Validate/dedup/exclude单源/共用Store/Builtin保留)

This commit is contained in:
wangjia
2026-07-29 06:38:52 +08:00
parent 52912268d0
commit 3159dd75c1
11 changed files with 285 additions and 36 deletions
+30 -4
View File
@@ -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:
+30 -4
View File
@@ -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]
+13 -10
View File
@@ -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(自托管,
+9 -3
View File
@@ -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
@@ -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 {
+24 -2
View File
@@ -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
+81 -2
View File
@@ -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)
}
}
+23 -8
View File
@@ -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
}
+37 -2
View File
@@ -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)
}
}
@@ -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")
@@ -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
);