这篇文章是一份 Windows 环境下用 Docker Compose 部署 CLIProxyAPI 的完整指南。我把实操中踩过的坑都写进来了，尤其是国内网络拉取官方镜像经常失败的问题——我们直接用本地构建绕过去。
部署完你能得到什么
部署成功后，你会拿到三样东西：
- API 核心服务地址：
http://localhost:8081，用于对接所有 AI 软件 - Web 管理后台：
http://localhost:8081/management.html，可视化管理所有 CLI 账号和模型 - 后端管理 API：
http://localhost:8081/v0/management/...
教程中凡是出现 CHANGE_ME_xxx 的地方，务必替换成你自己的密码或密钥。
为什么用 Docker 而不是原生部署
我知道很多人一听 Docker 就有点怵，觉得这是程序员才用的东西。但对于部署 AI 服务这类场景，Docker 真的是降低门槛最有效的方式。打个比方：原生安装就像毛坯房自己找工人拉电线砌墙，Docker 部署就是直接住进精装修公寓。
具体来说有三个好处：
- 环境隔离：所有依赖（Python 版本、各种包）全打包在容器里，不会跟你电脑上的环境冲突
- 零配置启动：不用折腾环境变量和底层库，一条命令跑起来
- 干净卸载：不想用了直接删容器，电脑上不留任何垃圾；换电脑的话，把配置挪过去就能一秒复原
准备工作：安装 Docker Desktop
如果你还没装 Docker，流程很简单：
- 去 Docker 官方网站下载 Windows 版的 Docker Desktop，一路 Next 装完，可能需要重启
- 重启后在开始菜单找到小鲸鱼图标的 Docker Desktop，双击打开
- 看到左下角绿色小鲸鱼图标或显示 "Engine running"，就说明引擎跑起来了
已经装过的直接跳过。
第一步：创建工作目录
在电脑上找个位置，比如 D:\claude code\CLIProxyAPI，作为项目根目录。最终的目录结构会很清爽。
第二步：拉取源码
打开命令提示符或 PowerShell，进入你的工作目录，把源码克隆下来。
第三步：核心配置
这里有个坑我必须提前说——Windows 用户在开始之前，一定要打开文件夹顶部的「查看」选项，把「文件扩展名」勾上。我当时就踩过这个雷，文件建成了 config.yaml.txt，启动直接全盘崩溃，排查了半天才发现是这个问题。
配置一：创建 docker-compose.yml
在项目根目录下新建 docker-compose.yml 文件。这里我们不用官方镜像，而是用刚克隆的源码做本地构建。原因很简单：官方镜像在国内大概率拉取失败（pull access denied），而且版本可能不是最新的。本地构建一劳永逸。
配置二：创建 config.yaml
在同一目录下新建 config.yaml，填入你的服务配置。
配置三：创建 auth 文件夹
这个很容易被忽略。如果不建这个空文件夹，容器启动会直接报错说 "auth 目录不可写"。在命令行里执行创建即可。
第四步：一键启动
配置完成后，在工作目录的命令行窗口里执行 Docker Compose 启动命令。
这个过程 Docker 会在本地编译镜像并下载底层依赖，可能花几分钟甚至更久，取决于网络情况。屏幕会疯狂滚日志，甚至看上去像卡住了——别关窗口，等到出现绿色的 "Started" 字样才算完成。
第五步：验证服务是否正常
最直观的方式是用浏览器。
验证管理界面：浏览器打开 http://localhost:8081/management.html，如果能看到带密码输入框的网页，输入你设置的 MANAGEMENT_PASSWORD 进入后台看到模型列表，说明后端完全正常。
验证 API 接口（可选）：打开一个新的命令行窗口，用 curl 请求模型列表 API。能返回 JSON 格式的模型列表，说明 API 已经可以被第三方软件调用了。
对接其他 AI 客户端
部署完成后，在 NextChat、Dify 或任何支持 OpenAI 格式的软件里，按这个公式填：
- API Base URL：
http://localhost:8081/v1（部分客户端可能不需要/v1后缀，看具体要求） - API Key：填你在
config.yaml里设置的CHANGE_ME_API_KEY - Model：填管理后台里看到的模型名称
常见问题排查
实操中踩坑最多的几个点：
- 官方镜像拉取失败：用本地构建方案绕过，这也是本文推荐的方式
- 文件扩展名问题：Windows 默认隐藏扩展名，务必提前打开显示
- auth 目录缺失：提前创建空的 auth 文件夹
- 构建过程中断：不要手动关闭窗口，耐心等待完成
这套方案的价值在于，你用一台普通的 Windows 电脑就能搭建起一个私有化的 API 中转服务，把各种命令行 AI 工具统一成标准接口。对于独立开发者来说，这意味着你可以用一套统一的方式管理和调用多个 AI 模型，不用为每个工具单独做适配。如果你正在用 Agent 框架或者搭建自动化工作流，这个中转层会帮你省掉不少对接的麻烦。