maskit

这是什么？适合谁？

Maskit（AGPL-3.0，Windows/macOS 桌面端 + Docker amd64/arm64）是一个架在”你的开发终端”与”外部大模型服务”之间的本地隐私防护网关。它要解决的问题很具体：用 Cursor / Claude Code / Codex / Pi / OpenCode / Aider 等任意 AI 编程工具时，代码里的 API Key、数据库连接串、内网 IP、手机号、身份证等敏感信息会不知不觉被发到外部模型服务商。

Maskit 的做法是双向透明代理：

• 出站自动打码：请求经过本地网关时，敏感数据被替换成结构化占位符（如 mysql://root:***@192.168.1.50:3306/db → {{CONNSTR_zkpmqx}}、李四 13800138000 → {{TERM_fnqtsw}} {{PHONE_bcdfgh}}），外部模型完全看不到真实数据；
• 回复流式还原：模型围绕占位符正常推理作答；响应回传时逐事件（SSE 流式）毫秒级把占位符还原成原文，保留原生打字机体验；
• 多轮会话一致性：同一长对话中”张三”在第 1 轮和第 10 轮始终映射为同一个占位符，模型逻辑推理不串号。

适合谁：在企业/合规环境下使用云端大模型 API 做编程、又不能把凭据与内网拓扑外发的开发者；用聚合网关/中转站（One API / New API）并希望统一出口脱敏的团队。

不适合谁：只用本地模型（Ollama 等）不出网的用户（无需此层）；对 AGPL-3.0 传染性敏感且要基于它改做商业闭源分发的团队。

使用前提：桌面端（Windows/macOS）或 Docker；你的 AI 工具必须支持配置 Base URL（绝大多数主流工具都支持）。

准备工作

1. 环境：Windows 或 macOS 桌面端；或 Docker（amd64/arm64）
2. 获取：GitHub Releases 下载安装包，或 docker pull 对应镜像
3. 成本：开源免费；Maskit 本身不收费，LLM 调用费用仍按你的上游 API 计
4. 时间：安装 + 首次接入一个工具约 10 分钟
5. 前置知识：知道怎么改自己工具的 API Base URL；理解”本地反向代理”概念
6. 替代方案：企业级 DLP/API 网关（重、贵）；自写 mitmproxy 脚本（费维护）；不脱敏硬发（不建议）

快速上手（3 步）

第一步：安装并启动 Maskit

桌面端从 Releases 下载安装后启动；Docker 用户拉镜像运行。启动后本地默认监听三个协议端口：

OpenAI 协议   http://127.0.0.1:18701/v1
DeepSeek 协议 http://127.0.0.1:18702/v1
Anthropic 协议 http://127.0.0.1:18703

（可自由添加修改，为不同模型/渠道分配独立本地端口。）

预期产出：Maskit 控制台可用，本地端口已监听。

第二步：把你的工具指到本地端口

以 Cursor 为例：Settings → Models → OpenAI Base URL 填 http://127.0.0.1:18701/v1，API Key 填你的真实 Key（Maskit 本地收到后安全转发给上游）。

Claude Code 用环境变量：

export ANTHROPIC_BASE_URL="http://127.0.0.1:18703"
claude

Codex / Pi / OpenCode / Aider 等任意命令行工具同理：

export OPENAI_BASE_URL="http://127.0.0.1:18701/v1"
export OPENAI_API_KEY="your-api-key"

预期产出：工具流量已走本地网关，正常对话不受影响。

第一步半（可选）：验证脱敏真的生效

在工具里发一条含敏感信息的请求，如”排查数据库：mysql://root:***@192.168.1.50:3306/db，联系人李四 13800138000”，然后打开 Maskit 的实时日志查看该笔请求：应看到出网内容已变成 {{CONNSTR_...}} / {{TERM_...}} {{PHONE_...}}，模型回答回传后原文无感还原。日志支持一键高亮原文对照。

预期产出：日志里”大模型收到的内容”不含任何真实敏感数据，“你最终看到的输出”是完整原文。

第三步：按需扩展

• 用敏感词库管理内部人名、项目代号（支持整词匹配与自定义正则，内置 19 类规则：API Key/Token、PEM 私钥、数据库连接串、手机号、身份证、邮箱、银行卡、内网 IP 等）；
• 接中转站/聚合网关：客户端管理 → 添加客户端 → 目标网关填中转商地址、本地端口选未占用端口、勾选预置脱敏路径；
• 代码接入：Python OpenAI(base_url="http://127.0.0.1:18701/v1", ...) 正常调用即全链路脱敏。

预期产出：脱敏面从默认规则扩展到你的业务术语。

常见踩坑（症状 → 原因 → 解决）

1. 占位符导致模型回答质量下降。症状：模型回答绕着 {{CONNSTR_...}} 打转不展开。原因：占位符本身信息量低，模型不知道连接串细节属正常。解决：把问题描述写得”脱敏无关”（结构、症状、预期行为），敏感值让模型给排查思路而非具体值；Maskit 的多轮一致性保证同一占位符语义稳定。
2. 跨 chunk 流式还原闪烁/错字。症状：打字机效果里占位符短暂露出。原因：占位符恰好被 SSE 分包切断。解决：Maskit 内置跨 chunk 缓冲拼接处理；若仍见异常，检查版本是否为最新（GitHub Releases）。
3. 担心关掉 Maskit 后工具断网。原因：反代进程退出后本地端口没人监听。解决：Maskit 的 Fallback Passthrough 兜底——退出软件后本地端口仍由轻量底层维持监听并透明直连转发，工具不会报网络错误（代价：该时段不脱敏，重开即可）。
4. 误以为要装 HTTPS 根证书。原因：习惯了一般抓包代理的做法。解决：Maskit 用多端口反代模式，只改 Base URL，无需向操作系统安装自签名 CA 根证书（避免中间人解密 HTTPS 的信任链问题）。
5. 多个工具抢同一个本地端口。解决：为每个工具/渠道分配独立端口（客户端管理添加），不要共用 18701。
6. 公司合规问”这软件会不会上传我的数据”。解决：README 声明 100% 本地运行、零外部遥测、无第三方统计 SDK；日志仅存本地。合规审计时可直接引用其架构文档。

初级用法

• 默认规则直接用：19 类内置正则低误报收敛核心隐私，装上即生效，不必先配置。
• 日志页当”出网审计”看：每笔请求的出网打码、上游响应、耗时分布都在日志里，定期翻一翻可发现”原来这个工具在发内网 IP”。
• 成本看板：Token 用量与费用估算按主流模型价格智能匹配，统计每日调用成本。

高级玩法

• 多轮滑动窗口 + 占位符复用：长会话中自定义敏感词的映射保持稳定，可以放心让 Agent 在第 N 轮引用第 1 轮提到的实体。
• 被动安全审计：实时监控模型回复中的错误泄露、身份换芯、Prompt 越权、命令执行风险提示——把”模型回复内容”也纳入防护面。
• 中转站统一出口：团队共用 One API/New API 网关时，把 Maskit 放在出口位置，所有人无感脱敏。
• SSE 逐事件还原 + 自定义正则：针对自家业务代号（如内部项目名）写正则规则，实现组织级词库。

小技巧

1. 先用”第一步半”的验证流程确认脱敏生效再日常使用，别默认装了就安全。
2. Fallback Passthrough 意味着”退出软件 = 退回明文直连”，长期挂着比用时开关更省心。
3. 高亮对照（日志里一键开关）是排查”为什么这句话没被打码”的最快工具。
4. 面向 Anthropic 的工具记得用 18703 端口（不带 /v1），OpenAI 协议才是 18701/v1，别填错。
5. 社区在 LINUX DO 论坛与 QQ 群（README 有入口），规则库踩坑可以交流。

常见问题 FAQ

Q1: 它和企业 DLP / API 安全网关有什么区别？

A: 定位不同。企业 DLP 面向全公司流量、策略重、部署重；Maskit 只做”开发终端 ↔ LLM 服务”这一跳的本地脱敏，个人装完即用，无需管理员。深度策略与审批流它不做。

Q2: AGPL-3.0 对我个人使用有影响吗？

A: 个人/内部使用没有影响。AGPL 的传染性约束在于”基于它做网络服务分发/修改后对外提供”的场景——商用集成前建议让法务确认边界（README 也是这个口径）。

Q3: 支持哪些模型协议？

A: 默认预置 OpenAI（18701）、DeepSeek（18702）、Anthropic（18703）三类协议端口，且支持任意第三方中转/聚合网关（自定义目标 + 端口 + 脱敏路径勾选）。

Q4: 脱敏后模型还能正常干活吗？

A: 能——这正是设计目标。占位符保留语义类别（CONNSTR/PHONE/TERM），模型可围绕”某连接串”推理；多轮一致性避免映射漂移。但对需要精确值的任务（如”连上这个库帮我查”）需你自己在本地执行真实值部分。

Q5: 会不会记录/上传我的对话内容？

A: README 声明纯本地运行、零遥测、不上传日志、无第三方 SDK。日志仅存本地磁盘，敏感环境可定期清理。本站未做流量抓包级验证，以官方声明 + 开源代码自审为准。

Q6: 和直接用 scrubber 类库（如 scrubadub）比？

A: scrubber 是”调用方主动调用”的库，要求改代码且只处理静态文本；Maskit 是透明网关，不改任何应用代码即对任意可配 Base URL 的工具生效，且带流式还原与审计界面。

免责声明

本文基于公开资料整理（GitHub README 中文版，核验日期 2026-09-14），AI 辅助生成，未在本站环境实际部署验证脱敏与还原效果。隐私防护声明（零遥测、本地运行）以官方 README 与开源代码为准，企业合规采用前建议自行审计。仓库创建于 2026-09-09（5 天），早期项目。

参考链接

• GitHub 仓库 xiaYuTian11/maskit
• Releases 下载
• 英文文档 README_EN.md
• 架构图 docs/architecture-zh.svg