frpc-console/Docs/install_docker.md

🐳 Docker 版安装指南

推荐方式：一键脚本自动部署，无需手动安装 Go 环境，无需预先配置 Docker 镜像源。

⚠️ 注意：Docker 版直接从源码构建，使用的是当前所选分支（LTS / Preview）的最新代码。如需使用特定 Release 版本，请查看 Releases 并通过二进制方式部署。

---

一、📥 前置条件

• 已安装 Docker（必须，版本不限）
• curl（其余依赖脚本会自动检查并安装）
• 操作系统：Linux（x86_64 / ARM64 / ARMv7 / ARMHF 均可）
• 网络：需能访问 Gitea 仓库（git.whitetop.xyz）

💡 脚本会自动检测并配置 Docker 镜像加速，无需手动设置。

---

二、🚀 一键部署（推荐）

在目标 Linux 服务器上执行：

curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash

部署过程中会提示选择通道：

· LTS（稳定版） → main 分支，生产环境推荐 · Preview（技术预览版） → test 分支，尝鲜和新特性验证

脚本会完整执行整个部署流程，包括镜像源自动检测与配置。

---

三、⚙️ 部署引擎自动完成内容

deploy.sh 是一个完整的状态机驱动部署引擎，按时间顺序执行以下操作：

阶段 步骤 说明 检测 检测操作系统 自动识别 openSUSE / Ubuntu / Debian / CentOS / Alpine / Arch 检测 检测 CPU 架构 自动适配 x86_64 / ARM64 / ARMv7 / ARMHF 检测 检测必要工具 git / curl / wget（如未安装则自动安装） 检测 检测 Docker 环境 确认 Docker 已安装，获取版本信息 检测 检测镜像源配置 读取 /etc/docker/daemon.json，检测用户配置和默认地址连通性 决策 状态机计算 根据检测结果决定：是否写入镜像源 / 是否重排 / 是否重启 Docker 决策 生成部署计划 展示完整操作清单，等待用户确认 执行 拉取源码 从 Gitea 仓库克隆对应分支的最新代码 执行 配置镜像源 按需写入 registry-mirrors，自动备份非法/空配置文件 执行 重启 Docker 如需生效，自动重启 Docker 服务（交互模式需确认） 执行 构建镜像 使用源码中的 Dockerfile 构建 frpc-console:${VERSION} 执行 清理旧容器 检测并删除已存在的 frpc-console 容器（如有） 执行 启动容器 挂载数据卷，--restart=always，--network host 执行 写入版本 将版本号写入 data/version.ini 验证 验证镜像内容 确认 /app/frpc-console 存在 验证 验证数据库 确认 SQLite 数据库可访问 验证 验证版本 确认容器内版本与目标版本一致 清理 清理旧镜像 保留最近 3 个镜像，自动删除更早版本 清理 清理临时文件 删除 /tmp/frpc-console-build

---

四、📂 数据持久化

脚本默认将数据存储在 /opt/frpc-console/data/：

文件 说明 frpc-console.db SQLite 数据库（用户、隧道、配置） frpc.toml 当前 frpc 配置文件 frpc.log frpc 运行日志 frpc.pid frpc 进程 PID version.ini 当前版本标识

升级或重建容器时，数据自动保留，不会丢失。

---

五、🔄 升级

方式一：重新运行部署脚本（推荐）

curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash

脚本会自动：

1. 拉取最新代码
2. 构建新镜像
3. 停止并删除旧容器
4. 启动新容器
5. 数据卷保持不变

方式二：手动更新

# 停止旧容器
docker stop frpc-console
docker rm frpc-console

# 重新运行 deploy.sh
curl -sSL https://git.whitetop.xyz/lxh2875931338/frpc-console/raw/main/run-deploy.sh | sudo bash

💡 升级时如检测到语义版本降级（如 2.6 → 2.5），脚本会自动备份数据目录，并等待用户确认后再执行。

---

六、🧹 常用命令

# 查看日志
docker logs -f frpc-console

# 查看 frpc 子进程状态
docker exec frpc-console ps aux | grep frpc

# 重启容器
docker restart frpc-console

# 停止容器
docker stop frpc-console

# 启动容器
docker start frpc-console

# 查看当前版本
cat /opt/frpc-console/data/version.ini

---

七、🌐 访问地址

部署完成后，浏览器打开：

http://你的服务器IP:9300

首次访问会自动跳转到注册页面，填写用户名和密码，完成管理员账户创建。

登录后，在「隧道列表」页面点击「导入 TOML」，即可将现有的 frpc.toml 迁移到 WebUI 中管理。

---

八、📌 手动部署（不使用脚本）

如果你已有源码，或想完全手动控制：

# 1. 克隆代码
git clone https://git.whitetop.xyz/lxh2875931338/frpc-console.git
cd frpc-console

# 2. 构建镜像
docker build -t frpc-console:latest .

# 3. 创建数据目录
mkdir -p /opt/frpc-console/data

# 4. 启动容器
docker run -d \
  --name frpc-console \
  --restart=always \
  --network host \
  -v /opt/frpc-console/data:/app/data \
  -e PORT=9300 \
  -e TZ=Asia/Shanghai \
  frpc-console:latest

⚠️ 手动部署不会自动处理镜像源配置、版本管理、容器冲突检测和镜像清理。建议优先使用一键部署脚本。

---

九、📖 相关文档

· 部署引擎设计详解 — 了解 deploy.sh 的状态机设计与工程决策 · 工程设计哲学 — 理解部署脚本背后的设计理念 · 二进制安装指南 — 适用于无 Docker 或边缘设备场景