## 🐳 Docker 版安装指南

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

> ⚠️ **注意**：Docker 版直接从源码构建，使用的是当前所选分支（LTS / Preview）的最新代码。如需使用特定 Release 版本，请查看 [Releases](https://git.whitetop.xyz/lxh2875931338/frpc-console/releases) 并通过二进制方式部署。

---

### 一、📥 前置条件

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

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

---

### 二、🚀 一键部署（推荐）

在目标 Linux 服务器上执行：

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

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

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

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

---

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

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

```mermaid
flowchart TD
    subgraph 检测阶段
        A[检测操作系统] --> B[检测CPU架构]
        B --> C[检测必要工具]
        C --> D[检测Docker环境]
        D --> E[检测镜像源配置]
    end

    subgraph 决策阶段
        E --> F[状态机计算]
        F --> G[生成部署计划]
        G --> H[用户确认]
    end

    subgraph 执行阶段
        H --> I[拉取源码]
        I --> J[配置镜像源]
        J --> K[重启Docker]
        K --> L[构建镜像]
        L --> M[清理旧容器]
        M --> N[启动容器]
        N --> O[写入版本]
    end

    subgraph 验证阶段
        O --> P[验证镜像内容]
        P --> Q[验证数据库]
        Q --> R[验证版本]
    end

    subgraph 清理阶段
        R --> S[清理旧镜像]
        S --> T[清理临时文件]
    end

    T --> U[部署完成]
```

---

四、📂 数据持久化

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

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

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

---

五、🔄 升级

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

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

脚本会自动：

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

方式二：手动更新

```bash
# 停止旧容器
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），脚本会自动备份数据目录，并等待用户确认后再执行。

---

六、🧹 常用命令

```bash
# 查看日志
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 中管理。

---

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

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

```bash
# 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
```

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

---

### 九、📖 相关文档

- [部署引擎设计详解](./deployment-engine-design.md) — 了解 `deploy.sh` 的状态机设计与工程决策
- [工程设计哲学](./engineering-philosophy.md) — 理解部署脚本背后的设计理念
- [二进制安装指南](./install_binary.md) — 适用于无 Docker 或边缘设备场景