new-api 系列（二）：安装部署——从零搭建 new-api

系列目录

1. （一）认识 new-api——新一代 AI API 管理网关
2. （二）安装部署——从零搭建 new-api（本文）
3. （三）渠道配置——接入各类模型提供商
4. （四）令牌与用户管理
5. （五）计价模型与成本控制
6. （六）监控、日志与告警
7. （七）生产环境部署与安全加固
8. （八）进阶——多实例、负载均衡与 SSO
9. （九）接入国内支付——支付宝、微信与自动充值
10. （十）接入国际支付——Stripe、PayPal 与海外收银

方式一：二进制直接运行（推荐）

这是最轻量的方式，适合 Linux 服务器。new-api 是 Go 编写的单二进制文件，不需要任何运行时依赖。

下载并安装

mkdir -p ~/new-api && cd ~/new-api

# 从 GitHub Releases 下载最新版（以 Linux amd64 为例）
# 访问 https://github.com/Calcium-Ion/new-api/releases 确认最新版本号
wget https://github.com/Calcium-Ion/new-api/releases/latest/download/new-api-linux-amd64 -O new-api
chmod +x new-api

# 验证
./new-api --version

常用平台文件名：

直接启动测试

./new-api --port 3000 --log-dir ./logs

此时浏览器访问 http://127.0.0.1:3000 就能看到登录页。默认使用 SQLite 数据库，文件自动创建在程序运行目录下。

配置 systemd 服务（生产环境必需）

直接用 ./new-api 启动在终端关闭后就停了。生产环境需要配置成系统服务。

sudo tee /etc/systemd/system/new-api.service > /dev/null <<EOF
[Unit]
Description=New API Service
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME/new-api
ExecStart=$HOME/new-api/new-api --port 3000 --log-dir $HOME/new-api/logs
Restart=always
RestartSec=5

# 安全加固
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=$HOME/new-api

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now new-api

# 检查状态
sudo systemctl status new-api

日志查看：

# systemd 日志
journalctl -u new-api -f

# 应用程序自身日志
tail -f ~/new-api/logs/new-api.log

指定 SQLite 数据库路径

如果想把数据库放在固定位置（方便备份），用 --sqlite-path 参数：

./new-api --port 3000 --sqlite-path /data/new-api/new-api.db

对应的 systemd 配置中修改 ExecStart：

ExecStart=$HOME/new-api/new-api --port 3000 --sqlite-path /data/new-api/new-api.db --log-dir $HOME/new-api/logs

方式二：Docker Compose

适合已有 Docker 环境的场景，或需要与其他服务编排。

准备 docker-compose.yml

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      - TZ=Asia/Shanghai

docker compose up -d

端口绑定说明：127.0.0.1:3000:3000 表示只监听本地回环地址。如果你打算直接对外暴露（不推荐），可以改成 3000:3000。生产环境建议始终绑定 127.0.0.1，通过 Nginx/Caddy 反代对外服务。

Docker 环境下的数据库

Docker 部署默认也使用 SQLite，数据文件在挂载的 ./data 目录下。如果需要 MySQL，在 environment 中添加数据库连接参数（见下文 MySQL 章节）。

方式三：从 one-api 迁移

如果你已经在用 one-api，new-api 支持直接读取 one-api 的数据库文件。

SQLite 迁移（最简单）

# 假设 one-api 数据库在 one-api 目录下
cp /path/to/one-api/one-api.db ~/new-api/

# 启动 new-api，指定 SQLite 数据库路径
./new-api --port 3000 --sqlite-path ~/new-api/one-api.db

new-api 启动时会自动检测并升级数据库 schema，原有的渠道、令牌、用户数据全部保留。

MySQL 迁移

如果你用的是 MySQL，不需要迁移数据。直接让 new-api 连接到同一个 MySQL 数据库即可。new-api 会自动升级表结构。

注意：升级前建议先备份数据库。升级是单向的，升级后的 schema 不再兼容 one-api。

# 备份 one-api 数据库
mysqldump -u root -p one-api > one-api-backup-$(date +%Y%m%d).sql

数据库选择：SQLite vs MySQL

建议：先用 SQLite 跑起来，等用户量真的上去了再切 MySQL。new-api 支持导出/导入数据，迁移不难。

切换 MySQL

在启动参数中添加 MySQL 连接信息：

./new-api \
  --port 3000 \
  --db-type mysql \
  --mysql-dsn "username:password@tcp(127.0.0.1:3306)/new-api?charset=utf8mb4&parseTime=True&loc=Local"

如果是 Docker 部署，在 environment 中设置：

environment:
  - DB_TYPE=mysql
  - MYSQL_DSN=username:password@tcp(host.docker.internal:3306)/new-api?charset=utf8mb4&parseTime=True&loc=Local

首次登录与安全设置

服务启动后，浏览器打开 http://127.0.0.1:3000：

登录后的首要操作：

1. 右上角头像 →「个人设置」
2. 修改用户名（建议不用 root）
3. 修改密码（建议 16 位以上随机字符串）
4. 如果不需要，删除默认的 root 用户，新建自己的管理员账号

生成强密码

openssl rand -base64 24

升级 new-api

new-api 更新频繁，建议关注 GitHub Releases。

二进制部署升级

cd ~/new-api

# 停止服务
sudo systemctl stop new-api

# 备份当前版本
cp new-api new-api.bak.$(date +%Y%m%d)

# 下载新版本
wget https://github.com/Calcium-Ion/new-api/releases/latest/download/new-api-linux-amd64 -O new-api
chmod +x new-api

# 启动服务（数据库自动迁移）
sudo systemctl start new-api

Docker 部署升级

docker compose pull
docker compose up -d

Docker 镜像更新后，重新 pull 并 up 即可。数据库文件在挂载的卷中，升级不会丢失数据。

验证安装

# 检查服务是否在运行
curl http://127.0.0.1:3000

# 应该返回 HTML（登录页面）

如果返回连接拒绝，检查：

# 端口是否在监听
ss -tlnp | grep 3000

# systemd 服务状态
sudo systemctl status new-api

# 日志
journalctl -u new-api -n 50

系列导航

系列导航

• （一）认识 new-api——新一代 AI API 管理网关
• （二）安装部署——从零搭建 new-api（本文）
• （三）渠道配置——接入各类模型提供商
• （四）令牌与用户管理
• （五）计价模型与成本控制
• （六）监控、日志与告警
• （七）生产环境部署与安全加固
• （八）进阶——多实例、负载均衡与 SSO
• （九）接入国内支付——支付宝、微信与自动充值
• （十）接入国际支付——Stripe、PayPal 与海外收银

实操清单

• 选择安装方式（二进制推荐；Docker 适合容器化环境）
• 下载对应平台的 new-api 二进制（GitHub Releases）
• 配置 systemd 服务（--port 3000 --log-dir /path/to/logs）并设为开机自启（systemctl enable）
• 启动服务，验证本地 :3000 可访问（curl http://localhost:3000）
• 登录后台，修改默认密码，创建独立管理员账号（sdmike，role 100）
• 确认日志目录正常写入（/home/sdmike/new-api/logs/ 有日志文件产生）
• 确认 systemctl status new-api 显示 active (running)
• 数据库文件（one-api.db）兼容 one-api 格式，可直接复制迁移