## 一、认识 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
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，输入验证命令：
```bash
docker version
```
能正常显示Client客户端、Server服务端版本信息，就说明Docker环境就绪，可以开始部署镜像。

## 三、实操部署：calciumion/new-api 一键运行
Docker环境就绪后，部署仅分**拉取镜像 + 运行容器**两步，全程复制粘贴命令即可，不同系统仅目录路径有区别，按需操作。

### 第一步：拉取国内稳定版镜像
打开终端或PowerShell，拉取实测**稳定可用版本 v1.0.0-rc.4** 国内镜像：
```bash
docker pull docker.xuanyuan.run/calciumion/new-api:v1.0.0-rc.4
```
拉取成功后终端会输出分层拉取完成、Digest校验信息，代表镜像已缓存到本地。

### 第二步：运行容器（分系统操作）
镜像下载完成后，执行对应系统运行命令，自动配置**开机自启、端口映射、时区校准、数据持久化挂载**，保障服务长期稳定运行。

#### 1. Windows系统（PowerShell执行）
自动创建D盘数据目录，启动容器：
```powershell
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标准目录规范：
```bash
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修改后命令：
```powershell
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修改后命令：
```bash
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:自定义端口`

![new-api 设置](https://developer.qcloudimg.com/http-save/yehe-2813964/5dd74e9a4214eae0c0b0c27be21a9de0.png)

能正常打开项目首页，即代表部署完成。

### 2. 后台初始登录账号密码
首次进入管理后台设置账号密码：

![new-api 设置密码](https://developer.qcloudimg.com/http-save/yehe-2813964/b7d5e02679ea0277b9cc630ac791c507.png)

建议第一时间修改密码，提升服务安全性。

![new-api 选择模式](https://developer.qcloudimg.com/http-save/yehe-2813964/f2c642f233b0b560c4c8f85e157afd5e.png)

![new-api 完成设置](https://developer.qcloudimg.com/http-save/yehe-2813964/8b09df7326858ad1cd85a6e91f86f4ff.png)

![new-api 首页](https://developer.qcloudimg.com/http-save/yehe-2813964/df2ae8cf6a06fd33557eba685cf3a0d8.png)

部署后，其他更多内容建议参考 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 中文镜像地址](https://xuanyuan.cloud/zh/r/calciumion/new-api)

也欢迎评论区留言交流。

觉得教程实用，欢迎收藏转发，分享给身边需要搭建AI接口服务的朋友！

calciumion/new-api 是一款基于One API二次开发的轻量AI大模型统一网关接口服务镜像，主打零复杂配置、跨平台兼容、极速部署。

轻量AI接口网关一键部署｜calciumion/new-api Windows/Linux Docker 部署全教程

推荐一款轻量高效的AI统一API服务镜像——calciumion/new-api，无需复杂配置，依托Docker即可一键极速部署。本文完整讲解Windows、Linux全环境部署流程，全程复制命令就能操作，纯新手也能快速落地，看完直接上手私有AI接口网关搭建。

运维

云计算

人工智能

开发工具

基于Docker一键部署calciumion/new-api，快速搭建轻量AI大模型统一网关。支持OpenAI标准接口格式，实现多模型集成、密钥管理及负载均衡。无需复杂配置，跨平台兼容，适合个人开发与团队协作。解决端口冲突问题，提供国内镜像加速，极速部署AI服务。

负载均衡

服务器

Windows

容器

Docker

CentOS

Ubuntu

Debian

Linux

2026采购季 | AI焕新·智启新局

apigw

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

轻量AI接口网关一键部署｜calciumion/new-api Windows/Linux Docker 部署全教程-腾讯云开发者社区-腾讯云

轻量AI接口网关一键部署｜calciumion/new-api Windows/Linux Docker 部署全教程

轻量AI接口网关一键部署｜calciumion/new-api Windows/Linux Docker 部署全教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐