ginka-role-fix

本地透明修复 GINKA API developer role 拒绝问题的小工具。

问题背景

DSH(DeepSeek Harness)等客户端通过 pi-ai 的 openai-completions 适配器调用 GINKA(api.ginka.cloud)的 deepseek-v4-flash 等模型时,系统提示词会被以 role: "developer" 发送。GINKA 网关只接受 system / assistant / user / tool 四种 role,直接返回 400:

invalid value: `developer`, supported values are: `system`, `assistant`, `user`, `tool`

工作原理

本工具在本地做透明拦截 + 定向改写,不需要修改任何客户端配置:

1. 在 hosts 文件写入 127.0.0.1 api.ginka.cloud,让本机所有发往该域名的 TLS 流量落到本地代理。
2. 代理监听 127.0.0.1:443,用自签 CA 签发的服务器证书终结 TLS(CA 已装入系统信任库,并通过 NODE_EXTRA_CA_CERTS 让 Node 程序生效)。
3. 只改写 POST /v1/chat/completions:解析 JSON body,把 messages[] 中 role: "developer" 的消息改为 role: "system";请求里没有 developer 时原字节透传(不做任何改动)。
4. 其余请求(/v1/models、网页、其他 API 路径等)一律字节级透传,不解析、不修改。
5. 出站连接通过 DNS 直连 GINKA 真实 IP(dns.resolve* 绕过 hosts 文件),并完整校验 GINKA 的真实证书,绝不跳过验证。

范围收敛说明:为了拦截 DSH 的请求,hosts 劫持覆盖整个域名,但改写动作只作用于 chat-completions 端点,其他流量只是经过本地代理转发,内容不变。

安装

要求 Node.js ≥ 18,root / 管理员权限(需要写 hosts、装证书、注册服务)。

# Linux / macOS
sudo npm install -g ginka-role-fix

# Windows(管理员 PowerShell)
npm install -g ginka-role-fix

全局安装的 postinstall 会自动完成:生成证书 → 写 hosts → 安装 CA → 注册并启动服务。 如果 postinstall 没有权限(非 root 安装),手动执行:

sudo ginka-fix install        # Linux / macOS
ginka-fix install             # Windows 管理员终端

注意:已打开的终端 / 正在运行的 DSH 进程需要重启才会加载新的信任锚点(NODE_EXTRA_CA_CERTS)。

systemd 服务不读 /etc/profile。 信任锚点通过 systemd 自己的机制下发:

• 用户管理器 / 用户服务(systemctl --user):/etc/environment.d/ginka-role-fix.conf
• 系统服务(如装在 /etc/systemd/system/ 的 dsh-web.service):/etc/systemd/system.conf.d/ginka-role-fix.conf 里的 ManagerEnvironment=(部分精简 systemd 缺系统侧 environment-d generator,/etc/environment.d 只喂得到用户管理器,故需要此项)

两者都在下次登录 / 重启后自动生效。想对正在运行的 manager 立即生效(不重启系统),注入后重启目标服务即可:

# 系统服务(例:dsh-web)
sudo systemctl set-environment NODE_EXTRA_CA_CERTS=/var/lib/ginka-role-fix/ca.crt
sudo systemctl restart dsh-web

# 用户服务
export NODE_EXTRA_CA_CERTS=/var/lib/ginka-role-fix/ca.crt
systemctl --user import-environment NODE_EXTRA_CA_CERTS
systemctl --user restart <your-service>

使用

ginka-fix status     # 查看安装状态(hosts / 证书 / 信任 / 服务 / 端口)
ginka-fix verify     # 端到端验证:本地证书握手 + 上游连通
ginka-fix log        # 查看最近 100 行日志(含每次改写记录)
ginka-fix uninstall  # 卸载:停服务、删 hosts 条目、移除 CA 与环境变量

卸载时 ginka-fix uninstall --purge 会连状态目录(证书)一起删除。

平台支持

| 平台 | 服务机制 | 证书信任 | 环境变量 | |------|----------|----------|----------| | Linux | systemd service(/etc/systemd/system/ginka-role-fix.service) | /usr/local/share/ca-certificates + update-ca-certificates | /etc/environment + /etc/profile.d/ + /etc/environment.d/ + /etc/systemd/system.conf.d/(systemd) | | macOS | launchd daemon(/Library/LaunchDaemons/com.ginka-role-fix.plist) | security add-trusted-cert(System keychain) | /etc/zshenv + /etc/profile | | Windows | 计划任务 ginka-role-fix(开机 ONSTART,SYSTEM) | certutil -addstore Root(user + machine) | setx NODE_EXTRA_CA_CERTS(当前用户) |

已知限制:

• 只支持 HTTP/1.1(undici / 各 OpenAI SDK 默认协议);HTTP/2 客户端会握手失败。
• Windows 上信任锚点按"安装用户"生效;其他 Windows 用户需要各自 setx(或重新运行 install)。
• WSL2 需要启用 systemd。

安全说明

• 代理只监听 127.0.0.1,不对外暴露。
• 只应答 SNI / Host 为 api.ginka.cloud 的连接,不充当开放代理。
• 出站连接校验 GINKA 真实证书(系统信任库),不降级验证。
• CA 私钥保存在状态目录(/var/lib/ginka-role-fix 或 C:\ProgramData\ginka-role-fix),仅本机签发使用。

开发

npm install        # 本地开发安装(postinstall 在非全局安装时是 no-op)
npm test           # node --test test/(单测 + 代理链路集成测试)
npm pack           # 构建发布包

调试环境变量(serve 时生效):GINKA_FIX_PORT、GINKA_FIX_UPSTREAM_PORT、GINKA_FIX_UPSTREAM_ADDRESS、GINKA_FIX_UPSTREAM_CA。

发布

npm login
npm publish

License

MIT