一、认识 calciumion/new-api 项目
calciumion/new-api 是一款基于One API二次开发的轻量AI大模型统一网关接口服务镜像，主打零复杂配置、跨平台兼容、极速部署。
无需手动搭建运行环境、安装依赖、调试繁杂配置，仅靠Docker一行命令，几分钟即可完成服务搭建。它核心作用是整合市面上所有主流AI大模型接口，将各类模型统一转为标准OpenAI接口格式，支持密钥集中管理、接口负载均衡、故障自动切换、调用统计权限管控等能力。
非常适合开发者接口调试、个人私有AI网关搭建、团队多模型统一管理、小型AI服务分发等场景。
中文镜像地址:https://xuanyuan.cloud/zh/r/calciumion/new-api
二、前置准备：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即可，图形化界面操作简单，小白也能轻松搞定：https://www.docker.com/get-started
安装完成后启动软件，桌面状态栏出现小鲸鱼图标即代表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模型统一管理、接口中转、密钥分发，个人自用、团队办公都非常合适。
部署遇到疑难问题，可前往官方中文镜像地址查阅文档:https://xuanyuan.cloud/zh/r/calciumion/new-api
也欢迎评论区留言交流。
觉得教程实用，欢迎收藏转发，分享给身边需要搭建AI接口服务的朋友！
