离线安装
推荐使用离线安装
离线安装是本产品推荐的部署方式。相比通过 1Panel 应用商店安装，它具有以下优势：
- 全程离线、开箱即用：离线包内置 Docker 离线安装包、网关镜像与 PostgreSQL 镜像，安装过程不依赖外网，也无需自行准备数据库实例。
- 自带 1gctl 命令行工具：安装完成后可直接在部署服务器上执行
1gctl完成服务状态检查、启停、重启、日志查看与卸载；通过 1Panel 应用商店方式部署的网关没有该工具。 - 不受 1Panel 版本限制：通过 1Panel 应用商店安装 PostgreSQL 版本，需要 1Panel v2.4.0 及以上版本；1Panel 版本低于 v2.4.0 时，应用商店的版本列表不会显示 PostgreSQL 版本。
- 避免数据库类型被锁定：SQLite 与 PostgreSQL 之间不能直接升级，也不能交叉恢复备份。通过 1Panel 应用商店以 SQLite 方式部署后，升级到 v1.4.0 仍只能继续使用 SQLite，无法切换为 PostgreSQL，除非重新部署。
1 适用场景
离线安装适用于部署服务器无法访问外网的内网、离线机房及涉密环境。
- 离线包内已包含安装所需的 Docker、容器镜像与依赖文件，安装过程不依赖外网。
- 社区版不提供 arm 架构离线包，如需在 arm 架构下部署，请采用在线安装方式。
2 环境要求
表 1 离线部署环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | 支持主流 Linux 发行版本（基于 Debian / RedHat，包括国产操作系统） |
| 服务器架构 | x86_64 |
| 容器运行时 | Docker。离线包内置 Docker 28.4.0 离线安装包：服务器未安装 Docker 时由安装脚本自动离线安装，已安装时跳过该步骤 |
| 浏览器 | Chrome、Edge 等现代浏览器 |
表 2 离线部署端口要求
| 端口 | 作用 | 说明 |
|---|---|---|
| 22 | SSH | 上传安装包、执行安装与后续维护 |
| 8080 | Web 控制台与 API | 默认访问端口，Web 管理界面和数据面 API 共用；如使用云服务器，请确保安全组已开放该端口 |
| 5432 | PostgreSQL | 仅容器网络内部使用，不对外暴露，无需在安全组或防火墙中开放 |
3 离线包内容
解压后的离线包目录结构如下所示（以 v1.4.0 amd64 为例）：
1panel-ai-gateway-v1.4.0-linux-amd64/
├── install.sh 安装脚本
├── upgrade.sh 升级脚本
├── 1gctl.sh 控制工具脚本（安装后注册为 1gctl 命令）
├── docker-28.4.0.tar.gz 内置 Docker 离线安装包
├── iptables-deb.tar.gz 内置 iptables 依赖包
├── docker-compose-postgres.yaml 容器编排文件
├── versions.txt 版本信息
└── images/
├── ai-gateway.tar.gz 1Panel AI 网关镜像
└── postgres.tar.gz PostgreSQL 镜像
表 3 离线包主要文件说明
| 文件 | 说明 |
|---|---|
install.sh | 安装脚本，交互式引导完成安装 |
upgrade.sh | 升级脚本，用于将已有安装升级到当前离线包版本 |
1gctl.sh | 控制工具脚本，安装后注册为 /usr/local/bin/1gctl 命令 |
docker-28.4.0.tar.gz | 内置的 Docker 离线安装包，服务器未安装 Docker 时使用 |
iptables-deb.tar.gz | 内置的 iptables 依赖包，供 Docker 离线安装使用 |
docker-compose-postgres.yaml | 容器编排文件，定义网关与 PostgreSQL 两个容器 |
versions.txt | 当前离线包的版本信息 |
images/ai-gateway.tar.gz | 1Panel AI 网关容器镜像 |
images/postgres.tar.gz | PostgreSQL 容器镜像 |
上表中的 1gctl.sh 在安装后即为 1gctl 命令行工具，其完整说明请参见 1gctl 命令行工具。
安装脚本会自动完成以下处理：
- Docker：检测服务器是否已安装 Docker。未安装时使用包内的
docker-28.4.0.tar.gz离线安装，已安装时跳过该步骤。 - 镜像：将包内的网关镜像与 PostgreSQL 镜像加载到本地，无需从外网或镜像仓库拉取。
- 数据库：加载 PostgreSQL 镜像并拉起数据库容器，无需自行准备 PostgreSQL 实例。
4 下载离线包
打开飞致云开源社区 1Panel AI 网关社区版下载页面，登录后下载最新版本的离线安装包。
图 1 社区版下载页
- 当前最新版本为 v1.4.0，安装包文件名为
1panel-ai-gateway-v1.4.0-linux-amd64.tar.gz。 - 下载页会同步提供各历史版本的安装包，可按需选择。
下载完成后，将离线包上传至部署服务器，下文以 /home 目录为例说明安装过程。
5 安装部署
5.1 解压安装包
以 root 用户通过 SSH 登录部署服务器，执行以下命令解压：
cd /home
# 请将示例文件名替换为实际下载的安装包名称
tar zxvf 1panel-ai-gateway-v1.4.0-linux-amd64.tar.gz
图 2 解压离线安装包
5.2 执行安装脚本
# 进入解压后的目录（目录名与安装包同名）
cd 1panel-ai-gateway-v1.4.0-linux-amd64
# 执行安装脚本
/bin/bash install.sh
安装脚本为交互式，会依次询问以下信息，直接回车即使用方括号中的默认值：
表 4 安装脚本交互项
| 提示 | 默认值 | 说明 |
|---|---|---|
| 请输入安装基础目录 | /opt | 安装目录为「基础目录 / 1panel-ai-gateway」，默认即 /opt/1panel-ai-gateway |
| 请输入网关端口 | 8080 | Web 管理界面与数据面 API 共用 |
| 请输入管理员用户名 | admin | 登录网关的管理员账号 |
| 请输入管理员密码 | ChangeMe | 需再次输入以确认；使用默认值时请登录后尽快修改 |
图 3 执行安装脚本
填写完成后脚本自动执行，依次完成解压依赖、安装 Docker、加载镜像、生成配置文件、安装控制工具、启动容器，并等待网关就绪：
- 解压
docker-28.4.0.tar.gz与iptables-deb.tar.gz，离线安装 Docker（服务器已安装 Docker 时跳过）； - 加载
images/ai-gateway.tar.gz与images/postgres.tar.gz两个镜像； - 生成配置文件
<安装目录>/.env； - 将控制工具安装到
/usr/local/bin/1gctl； - 启动网关与数据库容器，并轮询
http://127.0.0.1:<端口>/health/ready等待网关就绪。
5.3 安装结果
安装完成后，终端会输出访问地址、账号密码与目录信息：
表 5 安装完成后的输出信息
| 项目 | 说明 |
|---|---|
| 访问地址 | http://<服务器 IP 地址>:8080 |
| 管理员账号 | 安装时设置的管理员用户名，默认为 admin |
| 管理员密码 | 安装时设置的管理员密码，默认为 ChangeMe |
| 数据库密码 | AI-Gateway@2026!，仅首次初始化生效 |
| 安装目录 | /opt/1panel-ai-gateway |
| 数据目录 | /opt/1panel-ai-gateway/data |
| 控制工具 | 1gctl，支持 status / start / stop / restart / logs |
| 安装日志 | /opt/1panel-ai-gateway/install.log |
图 4 安装完成
安装完成后会启动两个容器：
表 6 离线安装启动的容器
| 容器名称 | 镜像 | 说明 |
|---|---|---|
1panel-ai-gateway | 1panel/ai-gateway:v1.4.0 | 网关服务，映射宿主机 8080 端口 |
1panel-ai-gateway-postgres | postgres:18.6 | 数据库服务，仅在容器网络内提供 5432，不对外暴露 |
6 登录访问
安装完成后，通过浏览器访问：
http://目标服务器 IP 地址:8080
- 用户名：安装时设置的管理员用户名，默认为
admin - 密码：安装时设置的管理员密码，默认为
ChangeMe
图 5 1Panel AI 网关登录页
若安装时使用了默认密码 ChangeMe，请在登录后尽快修改。
7 服务管理
离线安装会在部署服务器上注册控制工具 1gctl（实际路径 /usr/local/bin/1gctl），可直接在服务器上完成服务管理：
1gctl status # 查看服务状态与健康检查
1gctl start # 启动服务
1gctl stop # 停止服务
1gctl restart # 快速重启
1gctl logs # 查看日志
完整的命令、环境变量与退出码说明请参见 1gctl 命令行工具。
8 健康检查
安装脚本在启动容器后会自动等待网关就绪（http://127.0.0.1:8080/health/ready）。也可手动检查：
curl -fsS http://127.0.0.1:8080/health/live
curl -fsS http://127.0.0.1:8080/health/ready
/health/live返回{"status":"ok"}，表示 HTTP 进程可响应。/health/ready返回{"status":"ok"}，表示数据库和网关运行时已就绪。- 就绪检查失败时返回 503 和
{"status":"not_ready"}。
9 离线升级
离线升级与安装过程基本一致：下载新版本安装包并上传至部署服务器，解压后执行升级脚本即可。
cd /home
# 请将 <新版本号> 替换为实际下载的版本号
tar zxvf 1panel-ai-gateway-v<新版本号>-linux-amd64.tar.gz
cd 1panel-ai-gateway-v<新版本号>-linux-amd64
# 执行升级脚本
/bin/bash upgrade.sh
升级前请先备份数据目录（默认为 /opt/1panel-ai-gateway/data），避免升级异常导致数据丢失。
10 注意事项
- 请妥善保管离线包，不要从第三方渠道下载来源不明的所谓「离线包」，避免镜像被篡改。
- 目录与文件：安装目录默认为
/opt/1panel-ai-gateway，数据目录为安装目录下的data，配置文件为安装目录下的.env，安装日志为安装目录下的install.log；升级与迁移时需一并处理数据目录。 - 安装过程异常时，可查看安装日志
/opt/1panel-ai-gateway/install.log定位失败步骤。 - 卸载：执行
1gctl uninstall可移除容器、网络与控制工具；如需一并删除数据，请附加--purge参数。 - 忘记管理员密码时，可在部署服务器上执行以下命令重置：
docker exec -it 1panel-ai-gateway /usr/bin/ai-gateway reset-admin-password
详细操作请参见重置管理员密码。
- 修改端口等配置时，可编辑安装目录下的
.env，再执行1gctl start按当前配置重建有变更的容器（1gctl restart为快速重启，不应用配置变更）。 - 离线环境无法访问公有云模型 API 时，需要自行准备本地模型服务（如 vLLM 集群），并通过「账号池」接入。
- 如需使用 Elasticsearch，请另行准备外部实例，网关不负责其安装与运维。