AI网关本地住宅机器Docker一键部署
为什么要在本地住宅机器上部署 302AI 网关
302AI 网关是一个轻量的 AI 代理服务，能帮你统一管理多个大模型 API 的调用、实现负载均衡和流量转发。
如果你手上有一台闲置的台式机或 NAS，把它变成家庭 AI 网关，既省钱又可控。
本文会从零开始，教你用 Docker 一键部署这套服务，全程不用改任何复杂配置。
准备工作：环境与工具
硬件要求
- 一台能正常运行的电脑（Windows / Linux / macOS 均可）
- 至少 2GB 内存，20GB 可用磁盘空间
- 建议插着电，网络稳定
安装 Docker 环境
如果你还没装 Docker，请先按你的系统安装：
- Windows 10/11：下载 Docker Desktop for Windows，安装后启动 WSL2 后端
- Linux：执行
curl -fsSL https://get.docker.com | sh并加入用户组 - macOS：下载 Docker Desktop for Mac
安装完成后，打开终端输入 docker --version 和 docker compose version 确认环境就绪。
一键部署 302AI 网关的实操步骤
第一步：拉取项目与配置文件
使用 Git 克隆项目（如果 Git 没装，直接浏览器下载也行）：
git clone https://github.com/302ai/302ai-gateway-docker.git
cd 302ai-gateway-docker如果网络慢，也可以直接下载项目 ZIP 包解压。
第二步：编辑环境变量（可选）
项目根目录下有一个 .env.example 文件，复制成 .env：
cp .env.example .env用记事本打开 .env，根据你使用的 AI 服务填入对应的 API Key 和 Endpoint。
所有字段都有注释，按实际需要修改，不想修改也能直接用默认 Demo 调试验证。
第三步：使用 Docker Compose 一键启动
在项目目录下执行：
docker compose up -d等待镜像拉取和容器启动。
看到 Created 和 Starting 的日志后，说明启动成功。
常见问题与避坑指南
端口被占用怎么办？
默认端口是 3000，
如果被其他服务占用，
打开 docker-compose.yml，
修改 ports 映射，
比如改为 3001:，
3000
然后重新 docker compose up -d。
容器反复重启怎么办？
执行 docker compose logs 查看具体错误。
常见原因是 .env 中配置的 API Key 无效，或者网络不通。
检查网络，确保能访问外网。
住宅机器无法从外网访问？
本地部署默认只监听 127.0.0.1，如果需要局域网内其他设备访问，修改 docker-compose.yml 中的 ports 为 0.0.0.0:3000:3000。
注意防火墙放行该端口。
验证部署是否成功
打开浏览器，访问 http://localhost:3000，如果看到 302AI 网关的管理界面，就说明部署成功。
进一步测试：在管理界面添加一个测试的 API。
然后用 curl 测试转发：
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}]}'如果返回正常的 AI 响应，网关工作正常。
写在最后
通过本文，你应该已经在一台普通住宅机器上成功用 Docker 一键部署了 302AI 网关。
日常维护也很简单：更新镜像时执行 docker compose pull && docker compose up -d 即可。
如果你在部署中遇到其他问题，建议先去官方仓库的 Issues 中搜索，或者根据本文的避坑部分再检查一遍。
