API 代理转发环境搭建 -

piliqiu

2026-03-25 约 900 字预计阅读 4 分钟 - 次阅读

本文记录在 macOS 上从零搭建一套 API 代理转发与管理环境的完整过程，包含三个独立组件：

CLI Proxy API：负责将 CLI 工具的请求转发到目标服务
New API：统一管理和分发 API Key 的控制面板
codex-console：基于 Python 的前端控制台

这三部分可以独立部署，也可以组合使用。本文按实际落地顺序整理，重点放在环境准备、依赖管理和可维护性上。

前置条件

在开始之前，建议先确认以下条件：

macOS 系统，Apple Silicon 或 Intel 均可
已安装 Homebrew
已安装 Docker Desktop
有 GitHub 账号，并且可以访问相关仓库

这篇文章默认采用如下策略：

Go、Python、Bun 交给 Homebrew 管理
PostgreSQL、Redis 交给 Docker 管理
Python 项目使用 venv 创建独立虚拟环境
项目配置通过 .env 文件隔离

这样做的好处是安装路径清晰、版本切换简单，后续维护也更稳定。

统一环境管理

如果本机还没有 Homebrew，先安装它。后续的 Go、Python、Bun 都尽量通过 Homebrew 统一管理，避免手动下载安装到系统目录后再额外维护 PATH。

安装 Homebrew

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，将 brew 加入 shell 环境。

Apple Silicon：

1
2


eval "$(/opt/homebrew/bin/brew shellenv)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

Intel：

1
2


eval "$(/usr/local/bin/brew shellenv)"
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile

验证安装：

1

brew --version

一、CLI Proxy API

CLI Proxy API 的作用是将 CLI 工具的 API 请求转发到目标服务。

项目地址：

1

https://github.com/router-for-me/CLIProxyAPI

1. 安装 Go

直接使用 Homebrew 安装 Go：

1
2


brew install go
go version

通常情况下，Homebrew 安装后的 Go 会自动进入 PATH，不需要再手动写入 ~/.zshrc。如果终端没有识别 go，再检查 which go 和 echo $PATH。

2. 配置 Go 模块代理

在国内环境中，Go 依赖下载通常需要配置代理。下面几种方案任选其一即可。

直连模式：

1

go env -w GOPROXY=direct

官方可用代理：

1
2


go env -w GOPROXY=https://proxy.golang.com.cn,direct
go env -w GOSUMDB=sum.golang.google.cn

七牛云：

1
2


go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=goproxy.cn/sumdb/sum.golang.org

阿里云：

1

go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

如果你的网络环境比较稳定，也可以先保持默认配置，后续出现依赖下载失败再调整。

3. 拉取代码并编译

1
2
3
4
5
6
7


git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI

cp config.example.yaml config.yaml
# 根据实际情况编辑 config.yaml，填写转发配置

go build -o cli-proxy-api ./cmd/server

启动服务：

1

./cli-proxy-api

确认服务可以正常运行后，再配置开机自启。

4. 配置开机自启

macOS 上建议使用 LaunchAgent 管理用户级服务。

先创建目录：

1

mkdir -p ~/Library/LaunchAgents

然后写入 plist 文件。下面示例中的路径需要替换成你本机的实际路径：

 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


cat > ~/Library/LaunchAgents/com.cli-proxy-api.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cli-proxy-api</string>

    <key>ProgramArguments</key>
    <array>
        <string>/Users/yourname/CLIProxyAPI/cli-proxy-api</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/Users/yourname/CLIProxyAPI</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/yourname/CLIProxyAPI/app.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/yourname/CLIProxyAPI/app.log</string>
</dict>
</plist>
EOF

常用管理命令：

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


# 启动
launchctl load ~/Library/LaunchAgents/com.cli-proxy-api.plist

# 停止并卸载服务（不再开机自启）
launchctl unload ~/Library/LaunchAgents/com.cli-proxy-api.plist

# 重新加载并启动（修改配置后使用）
launchctl load ~/Library/LaunchAgents/com.cli-proxy-api.plist

# 手动启动（如果服务未运行）
launchctl start com.cli-proxy-api

# 手动停止
launchctl stop com.cli-proxy-api

# 查看服务状态
launchctl list | grep cli-proxy-api

二、New API

New API 是用于 API Key 统一管理和分发的面板。

项目地址：

1

https://github.com/QuantumNous/new-api

如果你希望对比其他实现，也可以参考：

1

https://github.com/Wei-Shaw/sub2api

这两个项目的定位接近，适合按自身需求选择。

New API 依赖 PostgreSQL 和 Redis。这里采用 Docker 部署，优点是依赖边界清晰，迁移和重建都比较方便。

1. 部署 PostgreSQL

创建 docker-compose-pg.yaml：

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


version: "3.8"

services:
  postgres:
    image: postgres:16
    container_name: postgres
    restart: unless-stopped
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: strong_password_here
      POSTGRES_DB: app_db
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pg_data:

启动：

1
2


docker compose up -d
docker compose down

2. 部署 Redis

创建 docker-compose-redis.yaml：

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


version: "3.8"

services:
  redis:
    image: redis:7.2
    container_name: redis
    restart: unless-stopped
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - redis_data:/data
    command: >
      redis-server
      --appendonly yes
      --requirepass strong_password_here

volumes:
  redis_data:

启动：

1
2


docker compose up -d
docker compose down

验证 Redis 是否正常：

1

docker exec -it redis redis-cli -a strong_password_here ping

如果返回 PONG，说明 Redis 已正常可用。

3. 拉取代码并配置环境

1
2
3
4
5
6
7


git clone https://github.com/QuantumNous/new-api.git
cd new-api

go mod tidy

cp .env.example .env
# 编辑 .env，填写数据库连接、Redis 地址等参数

4. 安装 Bun

New API 的前端构建需要 Bun。推荐直接使用官方安装方式：

1
2
3


curl -fsSL https://bun.sh/install | bash
source ~/.zshrc
bun --version

如果 shell 没有自动加载 Bun 的路径，再手动检查 .zshrc 或 .zprofile 中的配置。

5. 构建前端并启动后端

进入前端目录并构建：

1
2
3


cd web
bun install
bun run build

回到项目根目录启动后端：

1
2


cd /path/to/new-api
go run main.go

默认情况下，服务会监听 3000 端口，访问：

1

http://localhost:3000

即可进入管理面板。

6. 后台运行

1
2
3
4
5
6


nohup go run main.go 1>out.log 2>err.log &

tail -f out.log  # 实时查看输出

lsof -i :端口号
kill -9 12345

nohup：让程序忽略挂起信号（SIGHUP），即使终端关闭程序也能继续运行
1>out.log：将标准输出重定向到out.log文件
2>err.log：将标准错误重定向到err.log文件
&：将命令放到后台执行

三、codex-console

codex-console 是一个基于 Python 的前端控制台项目。

项目地址：

1

https://github.com/dou-jiang/codex-console

该项目建议使用 Python 3.13 或更高版本。

1. 安装 Python

使用 Homebrew 安装 Python：

1
2
3


brew install python@3.13
python3 --version
pip3 --version

安装完成后，通常已经可以直接使用 python3 和 pip3。

确认当前实际生效的路径：

1
2


which python3
which pip3

一般不需要再手动修改 PATH。只有在多个 Python 版本冲突时，才考虑补充 shell 配置。

2. 创建虚拟环境

进入项目目录后，创建独立虚拟环境：

1
2
3
4
5
6
7
8


git clone https://github.com/dou-jiang/codex-console.git
cd codex-console

cp .env.example .env
# 根据实际情况填写 .env

python3 -m venv .venv
source .venv/bin/activate

PyCharm 更推荐 .venv，PyCharm 会自动检测 .venv

激活成功后，终端前缀通常会出现 (.venv)。

3. 安装依赖并启动

1
2
3
4


pip install -r requirements.txt
# 连接到现有的数据库创建新库
docker exec -it postgres psql -U admin -d new-api -c "CREATE DATABASE \"codex-manager\";"
python webui.py

退出虚拟环境：

1

deactivate

4. 后台运行

1
2


mkdir -p ~/Library/LaunchAgents
vim ~/Library/LaunchAgents/com.codex.console.plist

 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


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

    <key>Label</key>
    <string>com.codex.console</string>

    <key>ProgramArguments</key>
    <array>
        <string>/Users/xxx/codex-console/.venv/bin/python</string>
        <string>/Users/xxx/codex-console/webui.py</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/Users/xxx/codex-console</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/xxx/codex-console/out.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/xxx/codex-console/err.log</string>

</dict>
</plist>

1
2
3
4
5


# 启动
launchctl load ~/Library/LaunchAgents/com.codex.console.plist

# 停止
launchctl unload ~/Library/LaunchAgents/com.codex.console.plist

总结

这套部署方案的核心思路很简单：

运行时依赖尽量分层管理
Go、Python、Bun 统一交给 Homebrew
PostgreSQL、Redis 交给 Docker
Python 项目使用 venv
每个项目独立配置 .env

这样做的好处是部署步骤更清晰，后续维护成本也更低。对于需要长期运行的本地服务，这种方式比手动下载安装到系统目录更稳，也更容易排障。