This is an automated email from the ASF dual-hosted git repository.
hsluoyz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/casbin-gateway.git
The following commit(s) were added to refs/heads/master by this push:
new 8d77d8f docs: add a Chinese README alongside the English default
8d77d8f is described below
commit 8d77d8f81a25c0359b7bb800d3b62706c957dcb9
Author: Yang Luo <[email protected]>
AuthorDate: Fri Aug 21 15:45:15 2026 +0800
docs: add a Chinese README alongside the English default
---
README.md | 4 +
README_zh.md | 259 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 263 insertions(+)
diff --git a/README.md b/README.md
index ca1bc39..2c2b876 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,10 @@
</a>
</p>
+<p align="center">
+ <b>English</b> | <a href="./README_zh.md">中文</a>
+</p>
+
## Run it
One command. No database, no Go, no Node, no configuration.
diff --git a/README_zh.md b/README_zh.md
new file mode 100644
index 0000000..a5f36a0
--- /dev/null
+++ b/README_zh.md
@@ -0,0 +1,259 @@
+<h1 align="center" style="border-bottom: none;">📦⚡️ Casbin Gateway</h1>
+<h3 align="center">一个开源网关，管理你机器上的 AI 编程 Agent 与 Web 流量，由 Go 和 React 开发。</h3>
+<p align="center">
+ <a
href="https://github.com/apache/casbin-gateway/actions/workflows/golangci-lint.yml";>
+ <img alt="Lint"
src="https://github.com/apache/casbin-gateway/actions/workflows/golangci-lint.yml/badge.svg";>
+ </a>
+ <a
href="https://github.com/apache/casbin-gateway/actions/workflows/build.yml";>
+ <img alt="Build"
src="https://github.com/apache/casbin-gateway/actions/workflows/build.yml/badge.svg";>
+ </a>
+ <a href="https://pkg.go.dev/github.com/apache/casbin-gateway";>
+ <img alt="Go Reference"
src="https://pkg.go.dev/badge/github.com/apache/casbin-gateway.svg";>
+ </a>
+ <a href="https://github.com/apache/casbin-gateway/releases/latest";>
+ <img alt="GitHub Release"
src="https://img.shields.io/github/v/release/apache/casbin-gateway.svg";>
+ </a>
+</p>
+
+<p align="center">
+ <a href="https://github.com/apache/casbin-gateway/blob/master/LICENSE";>
+ <img alt="license"
src="https://img.shields.io/github/license/apache/casbin-gateway";>
+ </a>
+ <a href="https://github.com/apache/casbin-gateway/issues";>
+ <img alt="GitHub issues"
src="https://img.shields.io/github/issues/apache/casbin-gateway";>
+ </a>
+ <a href="https://github.com/apache/casbin-gateway/stargazers";>
+ <img alt="GitHub stars"
src="https://img.shields.io/github/stars/apache/casbin-gateway";>
+ </a>
+ <a href="https://github.com/apache/casbin-gateway/network";>
+ <img alt="GitHub forks"
src="https://img.shields.io/github/forks/apache/casbin-gateway";>
+ </a>
+ <a href="https://discord.gg/S5UjpzGZjN";>
+ <img alt="Discord"
src="https://img.shields.io/discord/1022748306096537660?logo=discord&label=discord&color=5865F2";>
+ </a>
+</p>
+
+<p align="center">
+ <a href="./README.md">English</a> | <b>中文</b>
+</p>
+
+## 运行
+
+一条命令。不需要数据库，不需要 Go，不需要 Node，不需要配置。
+
+Linux 和 macOS：
+
+```bash
+curl -fsSL
https://raw.githubusercontent.com/apache/casbin-gateway/master/scripts/install.sh
| bash
+```
+
+Windows，在 PowerShell 中：
+
+```powershell
+irm
https://raw.githubusercontent.com/apache/casbin-gateway/master/scripts/install.ps1
| iex
+```
+
+两者都会下载适配本机的构建产物，解压到 `~/.local/share/casbin-gateway`（Windows 上是
`%LOCALAPPDATA%\casbin-gateway`），把 `casbin-gateway` 命令加入 PATH，然后启动它。接着打开：
+
+**http://localhost:17000** —— 用 `admin` 和密码 `123` 登录，然后在 **My Account** 里改掉它。
+
+安装到此为止。Gateway 把数据存在自己目录下的一个 SQLite 文件里，登录也走它自己的用户表。
+
+### 接下来做什么
+
+| 页面 | 你能得到什么 | 需要什么 |
+| --- | --- | --- |
+| **Agents** | 本机安装的每一个 AI 编程 Agent —— Claude Code、Codex CLI、Cursor 等等。点其中一个的
**Patch**，它的活动就会实时流进页面。 | 无 |
+| **Skills & MCP** | 所有 Agent 的所有技能和 MCP 服务器汇总在一张表里。可以打开、删除，或复制到另一个 Agent。 | 无
|
+| **Channels** | 挡在模型厂商前面的统一入口。API Key 由 Gateway 持有，Agent 拿不到。 | 一个厂商的 API Key
|
+| **LLM Records** | Agent 转发的每一次请求：完整的 system prompt、每一条消息和工具调用、模型可用的每个工具的
schema，以及 token 数和费用。 | 一个 Channel，以及 `llmRecordMode` —— 见[记录提示词](#记录提示词) |
+| **Advanced → Sites** | 反向代理 WAF：按站点的路由、规则、证书和统计。 | 打开代理 —— 见[开启 WAF
反向代理](#开启-waf-反向代理) |
+
+Agent 是通过读取 **Gateway 所在机器**的用户账户、home 目录和安装路径发现的，所以要在你想观察的那台机器上运行它。
+
+### 让 Agent 的流量走 Gateway
+
+这是 **LLM Records** 的数据来源，也是让 Gateway 而不是 Agent 持有厂商 Key 的方式。
+
+1. **Channels** → **Add**：选类型（OpenAI 兼容或 Anthropic 兼容），填厂商的 base URL 和 API
Key，并列出它提供的模型。
+2. **Agents** → 打开一个 Agent → 选中该 Channel。
+3. 复制页面显示的环境变量片段，在设置了这些变量的 shell 里启动 Agent：
+
+```bash
+export ANTHROPIC_BASE_URL="http://localhost:17000/v1/agents/claude-code";
+export ANTHROPIC_AUTH_TOKEN="casbin-gateway"
+```
+
+这个 token 只是占位符 —— Agent 没有它就拒绝启动，而 Gateway 会用 Channel 自己的 Key 去认证上游。
+
+### 停止、升级、卸载
+
+- **停止**：`Ctrl-C`。**再次启动**：在任意目录执行 `casbin-gateway` ——
这个命令是一个包装脚本，总是在安装目录（数据所在的地方）里启动 Gateway。
+- **升级**：再跑一遍安装命令。数据库和设置不受影响。
+- **卸载**：删除 `~/.local/share/casbin-gateway` 和
`~/.local/bin/casbin-gateway`（Windows 上是 `%LOCALAPPDATA%\casbin-gateway` 及其
PATH 条目）。
+
+设置 `INSTALL_DIR` 可以装到别的位置，`NO_START=1` 则只安装不启动。
+
+**这些是 nightly 构建**，每次推送都从 `master` 重新构建，并作为
[`nightly`](https://github.com/apache/casbin-gateway/releases/tag/nightly)
预发布版本发布。它们的用途是让人不装 Go 和 Node 工具链就能试用 Gateway；其他场景都应该从源码发布版构建。
+
+## 配置
+
+所有配置都是可选的。设置位于可执行文件旁边的 `conf/app.conf`，每一项在文件里都有说明。真正常被改动的是这些：
+
+| 配置项 | 默认值 | 作用 |
+| --- | --- | --- |
+| `httpport` | `17000` | Web UI 和 REST API 的端口 |
+| `driverName` / `dataSourceName` | `sqlite` / `./data/casbin-gateway.db` |
数据存放位置 |
+| `gatewayEnabled` | `false` | 打开反向代理 WAF |
+| `gatewayHttpPort` / `gatewayHttpsPort` | `80` / `443` | 代理监听的端口 |
+| `llmRecordMode` | `off` | 每次转发的 LLM 请求保留多少内容 |
+| `apiKeyEncryptionKey` | 空 | 加密存储 Channel 的 API Key（AES-256-GCM） |
+| `casdoorEndpoint` | 空 | 把登录切换到 [Casdoor](https://casdoor.org) SSO |
+
+Gateway 启动时会打印它实际在做什么，所以可以直接看结果而不用去查配置文件：
+
+```
++----------------------------------------------------------------------------+
+| Casbin Gateway |
++----------------+-----------------------------------------------------------+
+| Management UI | http://localhost:17000 |
+| Settings | conf/app.conf |
+| Web UI files | web/build |
+| Reverse proxy | enabled |
+| Gateway HTTP | :8080 |
+| Gateway HTTPS | :8443 |
+| Database | sqlite, file "./data/casbin-gateway.db" (connected) |
+| Sign-in | built-in user table, Casdoor is not configured |
+| App dir | ./data/apps |
++----------------+-----------------------------------------------------------+
+```
+
+如果端口被占用，Gateway 会指出是哪个进程占着它并停止启动，而不是半配置地跑起来。
+
+### 记录提示词
+
+在你主动要求之前，转发请求的内容一概不存储，因为提示词里可能粘进任何东西：
+
+```ini
+; "off" 什么都不留，"metadata" 记录谁调用了哪个模型、结果如何，
+; "full" 还会存下请求体 —— 这是 LLM Records 展示提示词、消息和
+; 工具 schema 所需要的。
+llmRecordMode = "full"
+llmRecordRetentionDays = 30
+llmRecordMaxRecords = 10000
+llmRecordMaxPayloadBytes = 1048576
+```
+
+请求体在存储前会被脱敏：看起来像凭据的内容会被替换掉，替换次数会随记录一起显示。请求头（入站 API Key 就在里面）根本不会进入记录。超过
`llmRecordMaxPayloadBytes` 的请求体会保留结构、只截断其中最长的字符串，所以一段很长的对话仍然能逐条消息列出来。
+
+每条记录旁边的费用用的是内置的官方标价，而厂商会调价、经销商也不按它来。把 `llmPricingFile` 指向你自己的费率 JSON 文件即可修正。
+
+### 开启 WAF 反向代理
+
+反向代理默认关闭，所以安装 Gateway 不会占用 80 和 443 端口。要使用它：
+
+1. **Advanced → Sites → Add**。**Domain**
填客户端会使用的主机名（`test.example.com`），**Host** 和 **Port** 填流量的去向（`127.0.0.1` 和
`8000`），**Mode** 选 `HTTP` —— 默认的 `HTTPS Only` 会在请求到达后端之前把明文 HTTP 重定向走。
+2. 在 `conf/app.conf` 里设 `gatewayEnabled = true` 并重启。Linux 和 macOS 上 80/443
端口需要 root，所以第一次尝试可以设 `gatewayHttpPort = 8080`。
+3. 在后端端口上起点什么，例如 `python -m http.server 8000`，然后用 `Host` 头请求这个站点 ——
网关就是按它路由的，所以不需要 DNS 或 `hosts` 记录：
+
+```bash
+curl -H "Host: test.example.com" http://127.0.0.1:8080/
+```
+
+你应该会拿到后端的响应。返回 `site not found for host` 说明请求到达了 Gateway，但没有站点匹配这个 `Host` 值。
+
+### 接入 Casdoor
+
+[Casdoor](https://casdoor.org) 是可选的，接管成员管理。在一个 Casdoor 实例里为 Gateway
创建组织和应用，然后填好 `casdoorEndpoint`、`clientId`、`clientSecret`、`casdoorOrganization`
和 `casdoorApplication`。只要设置了 `casdoorEndpoint`，登录就会跳转到 Casdoor，同时还会启用 [OAuth
登录](https://casdoor.org/docs/provider/oauth/overview)、健康检查告警、`CAPTCHA`
规则动作、按站点的 SSO 以及云端文件存储。
+
+## 开发
+
+### 环境要求
+
+Go 1.20+，以及带 Yarn 的 Node.js。
+
+### 从源码运行
+
+后端从 `web/build` 提供编译好的前端，所以先构建一次：
+
+```bash
+cd web && yarn install && yarn build
+```
+
+```bash
+go run main.go
+```
+
+然后打开 http://localhost:17000，用 `admin` 和密码 `123` 登录，和安装版一样。SQLite
数据库在首次启动时创建，不需要安装数据库服务。
+
+### 前端开发
+
+```bash
+cd web && yarn dev
+```
+
+这会在 http://localhost:16002 上提供带热更新的 UI，并把 API 请求代理到 17000 端口的后端，所以两边都得跑着。
+
+### 使用 MySQL 代替 SQLite
+
+项目用的是 XORM，所以它支持的每种数据库都能用。把 Gateway 指向你的服务器，首次启动时如果 `dbName` 不存在它会自动创建：
+
+```ini
+driverName = mysql
+dataSourceName = root:123@tcp(localhost:3306)/
+dbName = casbin_gateway
+```
+
+### 构建单文件二进制
+
+Gateway 平时会从磁盘读三样东西：`conf/app.conf`、`web/build` 里编译好的 UI，以及 IP 地理位置库
`ip/17monipdb.dat`。`embed` 构建标签会把这三样都打进可执行文件，安装脚本发布的就是这种产物：
+
+```bash
+cd web && yarn install && yarn build
+```
+
+```bash
+go build -tags embed -o casbin-gateway .
+```
+
+要先构建前端 —— `web/build` 下的所有内容都会进入二进制，该目录不存在时 `go build -tags embed` 会编译失败。
+
+磁盘上的文件始终优先于内嵌副本，所以单文件二进制照样可以被配置和用于开发，不必重新构建：
+
+| 内嵌资源 | 被什么覆盖 |
+| --- | --- |
+| `conf/app.conf` | 工作目录下、或可执行文件旁边的 `conf/app.conf` |
+| `web/build` | 工作目录下的 `web/build/index.html`，此后整个 UI 都从那里提供 |
+| `ip/17monipdb.dat` | 工作目录下的 `ip/17monipdb.dat` |
+
+启动摘要会报告每一项实际来自哪里。
+
+### 数据存放位置
+
+自包含说的是启动，不代表运行时只读。运行中的 Gateway 会相对于工作目录写入 `./data`（SQLite 数据库、部署的应用、Agent 的
patch 状态）、`./logs` 和 `./tmp` —— 这也是为什么安装出来的 `casbin-gateway`
命令是一个总在安装目录里启动它的包装脚本。直接在别处运行可执行文件，会在那里得到第二个空的安装。
+
+## 架构
+
+Casbin Gateway 包含 2 个部分：
+
+| 名称 | 说明 | 语言 | 源代码 |
+|----------|----------------------------------------|------------------------|----------------------------------------------------------|
+| 前端 | Casbin Gateway 的 Web 前端 UI | TypeScript + React + shadcn/ui |
https://github.com/apache/casbin-gateway/tree/master/web |
+| 后端 | Casbin Gateway 的 RESTful API 后端 | Golang + Beego + XORM |
https://github.com/apache/casbin-gateway |
+
+## 在线演示
+
+- 只读站点：https://door.caswaf.com （任何修改操作都会失败）
+- 可写站点：https://demo.caswaf.com （原始数据每 5 分钟恢复一次）
+
+## 文档
+
+https://caswaf.org
+
+## 贡献
+
+有任何问题欢迎提 issue，或者直接提 pull request —— 不过我们建议先开一个 issue 和社区讨论清楚。
+
+## 许可证
+
+[Apache-2.0](https://github.com/apache/casbin-gateway/blob/master/LICENSE)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
![https://github.com/apache/casbin-gateway/actions/workflows/golangci-lint.yml/badge.svg"](https://github.com/apache/casbin-gateway/actions/workflows/golangci-lint.yml/badge.svg"){kind=link}
![https://github.com/apache/casbin-gateway/actions/workflows/build.yml/badge.svg"](https://github.com/apache/casbin-gateway/actions/workflows/build.yml/badge.svg"){kind=link}
![https://pkg.go.dev/badge/github.com/apache/casbin-gateway.svg"](https://pkg.go.dev/badge/github.com/apache/casbin-gateway.svg"){kind=link}
![https://img.shields.io/github/v/release/apache/casbin-gateway.svg"](https://img.shields.io/github/v/release/apache/casbin-gateway.svg"){kind=link}