Skip to content

Commit 8ce9698

Browse files
whhjdiwhhjdi
authored
feat: 更新 README 文件 (#24)
1 parent 4fe1a0c commit 8ce9698

File tree

2 files changed

+218
-18
lines changed

2 files changed

+218
-18
lines changed

‎README.md‎

Lines changed: 60 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
# maxx
66

7+
English | [简体中文](README_CN.md)
8+
79
Multi-provider AI proxy with a built-in admin UI, routing, and usage tracking.
810

911
## Features
@@ -12,16 +14,21 @@ Multi-provider AI proxy with a built-in admin UI, routing, and usage tracking.
1214
- Provider routing, retries, and quotas
1315
- SQLite-backed storage
1416

15-
## Docker Compose (recommended)
16-
The service stores its data under `/data` in the container. The compose file
17-
already mounts a named volume so the SQLite DB is persisted.
17+
## Getting Started
1818

19-
```
19+
### 1. Start the Service
20+
21+
Start the service using Docker Compose (recommended):
22+
23+
```bash
2024
docker compose up -d
2125
```
2226

23-
Full example:
24-
```
27+
The service will run at `http://localhost:9880`.
28+
29+
**Full docker-compose.yml example:**
30+
31+
```yaml
2532
services:
2633
maxx:
2734
image: ghcr.io/awsl-project/maxx:latest
@@ -43,16 +50,51 @@ volumes:
4350
driver: local
4451
```
4552
53+
Service data is stored in the `/data` directory and persisted via volume.
54+
55+
### 2. Access Admin UI
56+
57+
Open your browser and visit [http://localhost:9880](http://localhost:9880) to access the Web admin interface.
58+
59+
### 3. Configure Claude Code
60+
61+
#### 3.1 Get API Key
62+
63+
Create a project in the maxx admin interface and generate an API key.
64+
65+
#### 3.2 Configure Environment Variables
66+
67+
**settings.json Configuration (Recommended, Permanent)**
68+
69+
Configuration location: `~/.claude/settings.json` or `.claude/settings.json`
70+
71+
```json
72+
{
73+
"env": {
74+
"ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
75+
"ANTHROPIC_BASE_URL": "http://localhost:9880"
76+
}
77+
}
78+
```
79+
80+
**Important Notes:**
81+
- `ANTHROPIC_AUTH_TOKEN`: Can be any value (no real key required for local deployment)
82+
- `ANTHROPIC_BASE_URL`: Use `http://localhost:9880` for local deployment
83+
84+
#### 3.3 Start Using
85+
86+
After configuration, Claude Code will access AI services through the maxx proxy. You can view usage and quotas in the admin interface.
87+
4688
## Local Development
4789

4890
### Server Mode (Browser)
4991
Backend:
50-
```
92+
```bash
5193
go run cmd/maxx/main.go
5294
```
5395

5496
Frontend:
55-
```
97+
```bash
5698
cd web
5799
npm install
58100
npm run dev
@@ -92,25 +134,25 @@ build-desktop.bat
92134

93135
## Release
94136

95-
创建新版本发布有两种方式：
137+
There are two ways to create a new release:
96138

97-
### GitHub Actions（推荐）
139+
### GitHub Actions (Recommended)
98140

99-
1. 进入仓库的 [Actions](../../actions) 页面
100-
2. 选择 "Release" workflow
101-
3. 点击 "Run workflow"
102-
4. 输入版本号（如 `v1.0.0`）
103-
5. 点击 "Run workflow" 执行
141+
1. Go to the repository's [Actions](../../actions) page
142+
2. Select the "Release" workflow
143+
3. Click "Run workflow"
144+
4. Enter the version number (e.g., `v1.0.0`)
145+
5. Click "Run workflow" to execute
104146

105-
### 本地脚本
147+
### Local Script
106148

107149
```bash
108150
./release.sh <github_token> <version>
109151
```
110152

111-
示例：
153+
Example:
112154
```bash
113155
./release.sh ghp_xxxx v1.0.0
114156
```
115157

116-
两种方式都会自动创建 tag 并生成 release notes。
158+
Both methods will automatically create a tag and generate release notes.

‎README_CN.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
<p align="center">
2+
<img src="web/public/logo.png" alt="maxx logo" width="128" height="128">
3+
</p>
4+
5+
# maxx
6+
7+
[English](README.md) | 简体中文
8+
9+
多提供商 AI 代理服务，内置管理界面、路由和使用追踪功能。
10+
11+
## 功能特性
12+
- 支持 Claude、OpenAI、Gemini 和 Codex 格式的代理端点
13+
- 管理 API 和 Web UI
14+
- 提供商路由、重试和配额管理
15+
- 基于 SQLite 的数据存储
16+
17+
## 如何使用
18+
19+
### 1. 启动服务
20+
21+
使用 Docker Compose 启动服务（推荐）：
22+
23+
```bash
24+
docker compose up -d
25+
```
26+
27+
服务将在 `http://localhost:9880` 上运行。
28+
29+
**完整的 docker-compose.yml 示例：**
30+
31+
```yaml
32+
services:
33+
maxx:
34+
image: ghcr.io/awsl-project/maxx:latest
35+
container_name: maxx
36+
restart: unless-stopped
37+
ports:
38+
- "9880:9880"
39+
volumes:
40+
- maxx-data:/data
41+
healthcheck:
42+
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9880/health"]
43+
interval: 30s
44+
timeout: 10s
45+
retries: 3
46+
start_period: 40s
47+
48+
volumes:
49+
maxx-data:
50+
driver: local
51+
```
52+
53+
服务数据存储在 `/data` 目录下，通过 volume 持久化。
54+
55+
### 2. 访问管理界面
56+
57+
打开浏览器访问 [http://localhost:9880](http://localhost:9880) 进入 Web 管理界面。
58+
59+
### 3. 配置 Claude Code
60+
61+
#### 3.1 获取 API 密钥
62+
63+
在 maxx 管理界面中创建项目并生成 API 密钥。
64+
65+
#### 3.2 配置环境变量
66+
67+
**settings.json 配置（推荐，永久生效）**
68+
69+
配置位置：`~/.claude/settings.json` 或 `.claude/settings.json`
70+
71+
```json
72+
{
73+
"env": {
74+
"ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
75+
"ANTHROPIC_BASE_URL": "http://localhost:9880"
76+
}
77+
}
78+
```
79+
80+
**重要提示：**
81+
- `ANTHROPIC_AUTH_TOKEN`：可以随意填写（本地部署无需真实密钥）
82+
- `ANTHROPIC_BASE_URL`：本地部署使用 `http://localhost:9880`
83+
84+
#### 3.3 开始使用
85+
86+
配置完成后，Claude Code 将通过 maxx 代理访问 AI 服务。您可以在管理界面中查看使用情况和配额。
87+
88+
## 本地开发
89+
90+
### 服务器模式（浏览器）
91+
后端：
92+
```bash
93+
go run cmd/maxx/main.go
94+
```
95+
96+
前端：
97+
```bash
98+
cd web
99+
npm install
100+
npm run dev
101+
```
102+
103+
### 桌面模式（Wails）
104+
详细的桌面应用文档请参阅 `WAILS_README.md`。
105+
106+
快速开始：
107+
```bash
108+
# 安装 Wails CLI
109+
go install github.com/wailsapp/wails/v2/cmd/wails@latest
110+
111+
# 运行桌面应用
112+
wails dev
113+
114+
# 构建桌面应用
115+
wails build
116+
# 或
117+
build-desktop.bat
118+
```
119+
120+
## API 端点
121+
- 管理 API: http://localhost:9880/admin/
122+
- Web UI: http://localhost:9880/
123+
- WebSocket: ws://localhost:9880/ws
124+
- Claude: http://localhost:9880/v1/messages
125+
- OpenAI: http://localhost:9880/v1/chat/completions
126+
- Codex: http://localhost:9880/v1/responses
127+
- Gemini: http://localhost:9880/v1beta/models/{model}:generateContent
128+
- 项目代理: http://localhost:9880/{project-slug}/v1/messages (等)
129+
130+
## 数据存储
131+
- 桌面模式（Windows）: `%APPDATA%\maxx`
132+
- 服务器模式（非 Docker）: `~/.config/maxx/maxx.db`
133+
- Docker 数据目录: `/data`（通过 `docker-compose.yml` 挂载）
134+
135+
## 发布版本
136+
137+
创建新版本发布有两种方式：
138+
139+
### GitHub Actions（推荐）
140+
141+
1. 进入仓库的 [Actions](../../actions) 页面
142+
2. 选择 "Release" workflow
143+
3. 点击 "Run workflow"
144+
4. 输入版本号（如 `v1.0.0`）
145+
5. 点击 "Run workflow" 执行
146+
147+
### 本地脚本
148+
149+
```bash
150+
./release.sh <github_token> <version>
151+
```
152+
153+
示例：
154+
```bash
155+
./release.sh ghp_xxxx v1.0.0
156+
```
157+
158+
两种方式都会自动创建 tag 并生成 release notes。

0 commit comments

Comments
 (0)