From fabcdf2b10ba52202246a2b1508e6cc13b9c60c3 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Mon, 10 Aug 2026 14:24:20 +0800
Subject: [PATCH] docs: add frpc client deployment guide (8 sections)

- Download frpc binary (architecture table)
- Download frpc.ini from web UI
- Install config + systemd unit
- Hot-reload after proxy changes
- Multi-instance scenario
- Troubleshooting table (6 common issues)
---
 README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)

diff --git a/README.md b/README.md
index 3ae62dd..d9f3d24 100644
--- a/README.md
+++ b/README.md
@@ -156,12 +156,162 @@ sudo systemctl enable --now frpc@laptop-jdoe
 ```
 
 改代理后：
+
 ```bash
 # 在 frpc 主机执行
 sudo frpc reload -c /etc/frpc/laptop-jdoe.ini
 # 或者 frpc reload -c /etc/frpc.ini（按你保存的路径）
 ```
 
+## 客户端（frpc）部署教程
+
+### 1. 下载 frpc 二进制
+
+frpc 和 frps 来自同一个 frp 发行包。在 frpc 主机上执行：
+
+```bash
+# 查看架构
+uname -m
+# x86_64 → amd64
+# aarch64 → arm64
+# armv7l → arm
+
+# 下载（以 amd64 为例，版本与服务器 frps 保持一致：0.70.1）
+cd /tmp
+curl -fSL -o frp.tar.gz \
+  https://github.com/fatedier/frp/releases/download/v0.70.1/frp_0.70.1_linux_amd64.tar.gz
+tar xzf frp.tar.gz
+sudo cp frp_0.70.1_linux_amd64/frpc /usr/local/bin/
+sudo chmod +x /usr/local/bin/frpc
+frpc --version
+# 应输出 0.70.1
+```
+
+其他架构替换 `amd64` 为 `arm64`、`arm` 等。
+
+### 2. 从 Web 管理界面下载 frpc.ini
+
+1. 登录 http://frps-manager-host:5390
+2. 进入「客户端」页面 → 找到你的客户端 → 点「frpc.ini」按钮下载
+3. 如果需要额外添加代理规则：在 Web 端「代理」页添加 → 再次下载 frpc.ini
+
+### 3. 安装配置文件
+
+```bash
+sudo mkdir -p /etc/frpc
+sudo cp ~/Downloads/frpc-laptop-jdoe.ini /etc/frpc/laptop-jdoe.ini
+sudo chmod 600 /etc/frpc/laptop-jdoe.ini
+```
+
+配置文件包含：
+- `server_addr` / `server_port` — frps 服务器地址
+- `token` — 共享认证 token（由管理员提供，不要外泄）
+- `admin_addr` / `admin_port` — 本地管理 API（用于 `frpc reload`）
+- 各 `[[proxies]]` 段 — 代理规则
+
+> 如果不想用 systemd，也可以直接运行测试：
+> ```bash
+> frpc -c /etc/frpc/laptop-jdoe.ini
+> # 看到 "login to server success" 表示连接成功
+> # Ctrl+C 停止
+> ```
+
+### 4. 安装 systemd 服务
+
+```bash
+# 从 frps-manager 仓库获取模板 unit 文件
+# （或者手动创建，内容见下方）
+sudo curl -fsSL -o /etc/systemd/system/frpc@.service \
+  https://raw.githubusercontent.com/AI-Agent/frps-manager/master/runtime/frpc@.service
+
+sudo systemctl daemon-reload
+
+# 启用并启动（%i 对应 /etc/frpc/ 下的文件名，不含 .ini）
+sudo systemctl enable --now frpc@laptop-jdoe
+```
+
+或者手动创建 `/etc/systemd/system/frpc@.service`：
+
+```ini
+[Unit]
+Description=frpc — fatedier/frp client (%i)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/frpc -c /etc/frpc/%i.ini
+Restart=on-failure
+RestartSec=5
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 5. 验证连接
+
+```bash
+# 查看服务状态
+sudo systemctl status frpc@laptop-jdoe
+
+# 看到以下关键日志表示成功：
+#   login to server success, get run id [xxxxx]
+#   proxy added: [ssh web]
+#   start proxy success
+
+# 查看实时日志
+sudo journalctl -u frpc@laptop-jdoe -f
+```
+
+回到 frps-manager Web 仪表盘 → 客户端列表里应显示「在线」状态，代理列表里对应代理应为绿色「在线」。
+
+### 6. 修改代理后热重载
+
+在 Web 端添加/修改/删除代理规则后：
+
+1. 回到「客户端」页 → 重新下载最新的 `frpc.ini`
+2. 在 frpc 主机上替换配置文件并 reload：
+
+```bash
+sudo cp ~/Downloads/frpc-laptop-jdoe.ini /etc/frpc/laptop-jdoe.ini
+sudo frpc reload -c /etc/frpc/laptop-jdoe.ini
+# 看到 "reload success" 表示生效
+# 无需重启 frpc 进程，已有的连接不受影响
+```
+
+> frpc.ini 中的 `admin_addr` / `admin_port` 段就是为 reload 准备的。
+> 如果你的 frpc 主机上运行了多个 frpc 实例，每个实例的 `admin_port` 必须不同。
+
+### 7. 多实例场景
+
+同一台主机跑多个 frpc 客户端（例如多个用户共享一台服务器）：
+
+```bash
+# 用户 A 的配置
+sudo cp frpc-alice.ini /etc/frpc/alice.ini
+# 用户 B 的配置（注意 admin_port 不同）
+sudo cp frpc-bob.ini /etc/frpc/bob.ini
+
+sudo systemctl enable --now frpc@alice
+sudo systemctl enable --now frpc@bob
+
+# 分别 reload
+sudo frpc reload -c /etc/frpc/alice.ini
+sudo frpc reload -c /etc/frpc/bob.ini
+```
+
+### 8. 故障排查
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| `token in login doesn't match` | token 错误或过期 | 重新从 Web 下载 frpc.ini |
+| `type [http] not supported when vhost http port is not set` | frps 未配 vhost 端口 | 联系管理员设置 `FRPS_VHOST_HTTP_PORT` |
+| `listen tcp :7400: bind: address already in use` | admin 端口冲突 | 改 frpc.ini 里的 `admin_port` |
+| `connection refused` | frps 未启动或防火墙 | 检查 `telnet frps-host 7000` |
+| Web 显示「离线」但 frpc 在跑 | frps dashboard 未同步 | 检查 frps dashboard (`:7500`) 是否可达 |
+| `reload success` 但代理没生效 | frpc.ini 里没写对应 proxy 段 | 重新从 Web 下载最新 frpc.ini |
+
 ## 配置（环境变量）
 
 | 变量 | 默认值 | 说明 |