一、认识 calciumion/new-api 项目
calciumion/new-api 是一款 基于 One API 二次开发的轻量 AI 大模型统一网关接口服务镜像 ，主打 零复杂配置、跨平台兼容、极速部署。
无需手动搭建运行环境、安装依赖、调试繁杂配置，仅靠 Docker 一行命令，几分钟即可完成服务搭建。它核心作用是 整合市面上所有主流 AI 大模型接口，将各类模型统一转为标准 OpenAI 接口格式，支持密钥集中管理、接口负载均衡、故障自动切换、调用统计权限管控等能力。
非常适合 开发者接口调试、个人私有 AI 网关搭建、团队多模型统一管理、小型 AI 服务分发 等场景。
二、前置准备：Docker 环境一键搞定
部署 calciumion/new-api 最优方式就是 Docker 容器化部署，隔离环境、无需操心依赖冲突，一条命令直接运行。先完成 Docker 环境安装，不同系统对应专属操作，新手照抄即可。
Linux 系统（含国产系统）一键安装
Ubuntu、CentOS、Debian，以及 银河麒麟、统信 UOS、欧拉 等国产 Linux 系统通用，无需手动换源、装依赖，复制以下一键脚本到终端执行，自动安装 Docker、Docker Compose，同时配置国内镜像加速，从根源解决镜像下载慢问题：
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
执行后等待几分钟，全程自动安装配置，无需任何手动干预。
Windows/Mac 用户
Windows 和 Mac 用户不用输复杂命令，直接下载 Docker Desktop 即可，图形化界面操作简单，小白也能轻松搞定：👉 Docker Desktop 官方下载
安装完成后启动软件，桌面状态栏出现小鲸鱼图标即代表 Docker 正常运行；Windows 用户务必等待 2~3 分钟，确保后台 Docker 服务完全初始化完毕，再进行后续部署。
验证 Docker 安装
环境安装完成后，打开 Linux 终端 / Windows PowerShell，输入验证命令：
docker version
能正常显示 Client 客户端、Server 服务端版本信息，就说明 Docker 环境就绪，可以开始部署镜像。
三、实操部署：calciumion/new-api 一键运行
Docker 环境就绪后，部署仅分 拉取镜像 + 运行容器 两步，全程复制粘贴命令即可，不同系统仅目录路径有区别，按需操作。
第一步：拉取国内稳定版镜像
打开终端或 PowerShell，拉取实测 稳定可用版本 v1.0.0-rc.4 国内镜像：
docker pull docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
拉取成功后终端会输出分层拉取完成、Digest 校验信息，代表镜像已缓存到本地。
第二步：运行容器（分系统操作）
镜像下载完成后，执行对应系统运行命令，自动配置 开机自启、端口映射、时区校准、数据持久化挂载，保障服务长期稳定运行。
1. Windows 系统（PowerShell 执行）
自动创建 D 盘数据目录，启动容器：
mkdir D:\new-api -Force; docker run -d --name new-api --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v D:\new-api:/data docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
命令简易说明
- 自动创建本地数据目录，挂载到容器实现数据持久化，删除容器也不会丢失配置数据；
- –restart always 配置容器开机自启，系统重启服务自动恢复；
- -p 3000:3000 端口映射，本地 3000 端口访问服务；
- 校准上海时区，避免后台时间、日志时间错乱。
2. Linux 系统
终端执行以下命令，适配 Linux 标准目录规范：
mkdir -p /data/new-api; docker run -d --name new-api --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /data/new-api:/data docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
命令逻辑和 Windows 完全一致，仅本地数据存放路径不同。
四、高频避坑：3000 端口冲突
很多小伙伴启动容器时，会遇到经典端口占用报错：
docker: Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:3000 -> 127.0.0.1:0: listen tcp 0.0.0.0:3000: bind: Only one usage of each socket address
报错原因：本地 3000 端口已被其他软件、后台服务、站点程序占用，Docker 无法绑定端口。
两种解决方法（推荐方法一，零改动最省事）
方法 1：修改本地映射端口（首选）
不用关闭任何已有程序，只改端口映射格式：本地闲置端口: 容器 3000，示例改用 3001 端口：
Windows 修改后命令：
mkdir D:\new-api -Force; docker run -d --name new-api --restart always -p 3001:3000 -e TZ=Asia/Shanghai -v D:\new-api:/data docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
Linux 修改后命令：
mkdir -p /data/new-api; docker run -d --name new-api --restart always -p 3001:3000 -e TZ=Asia/Shanghai -v /data/new-api:/data docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
修改完成后，访问地址改为：http://127.0.0.1:3001 即可。
方法 2：关闭占用 3000 端口程序
若必须使用 3000 端口，先结束占用进程：
- Windows：PowerShell 执行
netstat -ano | findstr :3000查出进程 PID，任务管理器结束对应进程； - Linux：终端执行
lsof -i:3000查看占用进程，执行kill -9 进程 ID关闭后重新启动容器。
五、部署验证 + 后台登录 + 容器常用管理
1. 部署成功验证
容器启动后，浏览器访问：默认端口：http://127.0.0.1:3000 改端口后：http://127.0.0.1: 自定义端口
能正常打开项目首页，即代表部署完成。
2. 后台初始登录账号密码
首次进入管理后台设置账号密码：
建议第一时间修改密码，提升服务安全性。
部署后，其他更多内容建议参考 new-api 官方文档进行配置 https://docs.newapi.pro/zh ，本文不做过多介绍。
3. 新手必备容器管理命令
日常启停、排查日志直接复制使用：
- 查看容器运行状态：
docker ps | grep new-api - 停止服务容器：
docker stop new-api - 重启服务容器：
docker restart new-api - 删除旧容器（需先停止）：
docker rm new-api - 查看运行日志（排查报错）：
docker logs new-api
六、总结
calciumion/new-api 作为轻量 AI 统一接口网关，最大优势就是 开箱即用、跨平台兼容、部署零难度。不管是 Windows 电脑、普通 Linux 服务器，还是银河麒麟、统信 UOS 等国产系统，只要装好 Docker，复制本文命令就能一键部署。
本文针对性解决了新手最头疼的 3000 端口冲突 问题，同时配备国内高速镜像，彻底解决拉取慢、超时问题。部署后可实现多 AI 模型统一管理、接口中转、密钥分发，个人自用、团队办公都非常合适。
部署遇到疑难问题，可前往官方中文镜像地址查阅文档：calciumion/new-api 中文镜像地址
也欢迎评论区留言交流。
觉得教程实用，欢迎收藏转发，分享给身边需要搭建 AI 接口服务的朋友！