ChmlFrp 内网穿透部署文档
新版 0.70.1 的两条部署路线(多服务守护 / systemd 托管),加上旧版 0.50 教程的存档。面向零基础:照着复制、只改两行、能跑起来,出问题知道先看哪里。
这份文档怎么用
三句话:
- 你要把内网机器(NAS、软路由、树莓派、旧电脑)上的服务通过 ChmlFrp 暴露到公网,就照着第一部分做。
- 新版有两条路:用
multi_runner一个脚本管多条命令,或者用系统自带的systemd管一条 frpc。选一条用,不要让两个东西同时管同一个 frpc。 - 旧版 0.50 的教程原样保留在第二部分,只修了显示问题和文字错误,方便旧机器对照。
点一下就能整段复制,复制到的内容不含行号、不含语言标签。命令里的占位符(令牌、隧道 ID、路径)仍然要换成你自己的。
30 秒选路线
| 你的情况 | 建议 | 直接跳到 |
|---|---|---|
| 只跑一个 frpc,想省事、开机自启、崩了自动拉起 | 用 systemd | 教程二 · 新手版 |
| 一台机器要跑好几个 frpc,或者 frpc 之外还有别的程序要守护 | 用 multi_runner | 教程一 · 新手版 |
命令里写了 cd、&&、管道,怎么都起不来 | 看脚本的解析规则 | 教程一 · 高手版 |
想知道 systemd 为什么不认 cd、为什么不自启 | 看 systemd 的进程模型 | 教程二 · 高手版 |
| 手上是 0.50 / 0.51 的旧机器、旧配置 | 查存档 | 旧版教程 |
先认清这几个词
| 词 | 一句话解释 |
|---|---|
| frpc | 客户端,跑在你内网这台机器上,负责把本地服务「送出去」 |
| frps | 服务端,跑在公网服务器上。用 ChmlFrp 的话它已经替你跑好了,你不用管 |
| 隧道 | 一条「公网地址 ↔ 内网地址」的映射,在面板上创建 |
| 用户令牌 | 面板上那串身份凭据。0.70.1 用 -u 传 |
| 隧道 ID | 面板上每条隧道的编号。0.70.1 用 -p 传 |
| 守护 | 程序挂了自动拉起、开机自动启动。这是本文一半篇幅在讲的事 |
| 内网穿透 | 让公网能访问到你没有公网 IP 的内网服务 |
地址栏的 # 会记录进度
读到哪一节,地址栏就会变成 ...#t2-newbie 这样的形式,左侧目录里对应的条目也会高亮。把这条完整链接收藏或发给别人,下次打开会直接回到这一节。
文档里的占位符
| 文档里写的 | 你要换成 |
|---|---|
/svr/frpc | 你实际存放 frpc 的目录(本文统一用它举例) |
frpc.toml | 你的配置文件名。旧版是 frpc.ini |
你的用户令牌 | 面板里的用户令牌 |
你的隧道ID | 面板里的隧道编号,多个用英文逗号分隔 |
用户名 | 你登录 NAS / 服务器的用户名 |
本文命令都按「已 SSH 登录 Linux,普通用户可用 sudo」来写。旧版存档里的命令则假定你使用 root 或 sudo。看到 sudo 就说明这条要管理员权限,不要漏。
新版教程:ChmlFrp 0.70.1
0.70.1 的压缩包里同时带了 frpc(客户端)、frps(服务端)和两个空的配置文件。你只需要 frpc,frps 可以删掉。
这一部分有两条互不冲突的路线,每条都分「新手版」和「高手版」:
| 教程 | 解决的问题 | 适合谁 |
|---|---|---|
| 教程一 · 多服务守护 | 一个脚本读 services.conf,一行一条命令:启动、崩溃重启、按服务写日志 | 一台机器要跑多条命令 |
| 教程二 · systemd 托管 | 用系统自带的 systemd 托管 frpc:开机自启、崩溃重启、日志统一 | 只跑一条 frpc,越少依赖越好 |
0.70.1 通用说明
不管走哪条路,下面四件事都要先知道,能省掉一半的「怎么起不来」。
压缩包里有什么
以 ChmlFrp-0.70.1_261019_linux_amd64.tar.gz 为例,解压后是一个同名目录:
| 文件 | 说明 | 你要不要用 |
|---|---|---|
frpc | 客户端主程序 | 要,就是它连服务端 |
frps | 服务端主程序 | 不用,ChmlFrp 已经替你跑了 |
frpc.toml | 客户端配置文件,空文件 | 用法 B 才需要,把面板配置粘进去 |
frps.toml | 服务端配置文件,空文件 | 不用 |
LICENSE | 许可证 | 不用 |
配置文件的两种用法
ChmlFrp 面板给你的东西,通常是下面两种之一,二选一,不要混用:
用法 A:面板给的是一条启动命令(远程配置)
./frpc -u 你的用户令牌 -p 你的隧道ID
这种模式下配置由服务端下发,本地不需要配置文件。-p 可以写多个隧道 ID,用英文逗号分隔。
用法 B:面板给的是一整份配置文件
把它保存成 frpc.toml,然后显式指定:
./frpc -c frpc.toml
一份最小可用的 frpc.toml 长这样(字段名与 frp 0.70 一致,实际值以面板为准):
serverAddr = "你的服务器地址"
serverPort = 7000
auth.method = "token"
auth.token = "你的令牌"
[[proxies]]
name = "nas-web"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5000
remotePort = 12345
-c 会去找 frpc.inifrpc 的默认配置路径是 ./frpc.ini,而 0.70.1 的包里给的是 frpc.toml。所以必须写 -c frpc.toml,否则会直接报:
open ./frpc.ini: no such file or directory
这不是配置写错了,是它根本没找到文件。
装好先验证配置
0.70.1 自带配置校验命令,改完配置先跑它,比「重启完才发现写错」快得多:
./frpc verify -c frpc.toml
看到下面这行就说明格式没问题:
frpc: the configuration file ... syntax is ok
0.70.1 默认开启严格校验(--strict-config),字段名拼错会直接报错,例如:
json: unknown field "bogusField"
改字段名,或者对照面板生成的配置逐字核对。
与旧版 0.50 的差异
| 项目 | 旧版 0.50(第二部分存档) | 新版 0.70.1 |
|---|---|---|
| 配置文件 | frpc.ini,INI 格式 | frpc.toml,TOML 格式,包内是空文件 |
| 默认配置路径 | ./frpc.ini | 仍是 ./frpc.ini,所以用 toml 必须写 -c |
-u 的含义 | 用户 ID | 用户令牌(--user-token) |
-p 的含义 | 隧道 ID | 隧道 ID 列表(--tunnel-ids),可逗号分隔 |
| 配置检查 | 没有 | frpc verify -c frpc.toml |
| 热重载 | 没有 | frpc reload(需要开管理端口,日常仍建议 restart) |
| 严格配置 | 没有 | 默认开启,字段拼错直接报错 |
| 包内文件 | 只有 frpc | frpc + frps + 两个空配置 + LICENSE |
./frpc -v 会直接打印,例如 ChmlFrp-0.70.1_261019。排错时先把这个版本号记下来,再对照本文,能避免「拿旧教程套新版本」。
教程一 · 多服务守护(multi_runner)
multi_runner 是跑在 Linux 上的守护脚本:默认读脚本同目录的 services.conf(也可以把别的路径当参数传进去),一行启动一条命令,进程退出后按间隔重启,输出写进 logs/。它不依赖 systemd,但建议和 systemd 配合——systemd 守住 multi_runner,multi_runner 守住你的命令。
它解决的是这种场景:一台机器上既有 frpc,又有别的常驻程序,每个都写一份 systemd 服务文件太啰嗦;或者同一条命令要反复重启、还想把日志按服务分开。
| 版本 | 内容 | 适合 |
|---|---|---|
| 新手版 | 目录怎么摆、services.conf 怎么写、怎么启动、怎么重启、出问题看哪 | 第一次用,只想让它跑起来 |
| 高手版 | 三层解析链路、shlex 分词规则、bash -c 引号写法、进程与信号、陷阱清单 | 命令总起不来,或者要写复杂命令 |
高手版里的每一条规则,新手版都已经替你写成了固定写法。跑通之后再读,会轻松很多。
本教程的命令用 -c frpc.toml。如果你用的是 0.50 旧版,把文件名换成 frpc.ini 即可,其余写法完全一样。
教程一 · 新手版(照着改就能跑)
这一版只解决四件事:放哪、怎么写、怎么启动、出问题看哪。语法原理一概不讲,需要时再翻高手版。
它到底替你干了什么
你只需要维护一个纯文本文件 services.conf,里面一行一条命令:
/svr/frpc/frpc -c /svr/frpc/frpc.toml
剩下的它来做:
| 它做的事 | 对你的意义 |
|---|---|
| 逐行启动命令,全部并行、互不阻塞 | 不用给每个程序写一份 systemd 服务文件 |
崩溃(退出码非 0、被信号杀)后等 interval 秒再拉起 | 半夜崩了也能自己回来 |
每条命令的输出单独写进 logs/,文件名是 序号_程序名.log | 出问题知道是哪一条在报错 |
| 停止时先发 TERM,等 5 秒再 KILL | 一般不会留下杀不掉的残留进程 |
首次运行自动生成 services.conf | 不用自己从零写格式 |
它不管开机自启(要靠 systemd 守住它),也不做端口转发本身。它只是「命令的运行器」。
第一步:把目录和文件摆好
以 /svr/frpc 为例,换成你自己的目录也行,后面的路径跟着改:
/svr/frpc/
├── frpc ← 0.70.1 包里的可执行文件
├── frpc.toml ← 0.70.1 包里的配置文件(把面板配置粘进去)
├── multi_runner.py ← 守护脚本
├── services.conf ← 第一次运行后自动生成
└── logs/ ← 第一次运行后自动生成
先把目录建出来:
sudo mkdir -p /svr/frpc
然后把 frpc、frpc.toml、multi_runner.py 放进去(WinSCP 拖拽或 scp 都行),再加执行权限:
sudo chmod +x /svr/frpc/frpc
chmod +x 只做一次。忘了这一步的典型现象是:命令明明没错,却一直重启,日志里写 Permission denied。
第二步:先跑一次,让它生成配置
services.conf 不用手写,脚本第一次运行会自己在同目录生成一份带注释的模板:
cd /svr/frpc
python3 multi_runner.py
它会打印这两行,然后退出:
已创建配置文件: /svr/frpc/services.conf
请编辑该文件,写入要启动的命令,然后重新运行本脚本。
这是正常现象,不是报错。它此时还没有任何命令可执行。
如果你已经配好了 multi_runner.service 再去启动,它会「生成配置 → 退出 → 被 systemd 拉起 → 再退出」,日志每 10 秒刷一次。先按下面的步骤把配置写好,再交给 systemd。
第三步:先把命令手动跑通
不要一上来就交给守护脚本。 先在终端把要托管的命令原样跑一遍:
cd /svr/frpc
./frpc -c frpc.toml
看到 login to server success 之类的日志,说明配置和网络都没问题,按 Ctrl+C 停掉。
这一步的意义:命令本身有问题(配置错、令牌错、网络不通)时,守护脚本只会「重启—失败—再重启」,日志刷得飞快,反而看不出原因。手动跑一次,报错直接打在屏幕上。
第四步:编辑 services.conf
sudo nano /svr/frpc/services.conf
文件里已经有三行全局配置和一堆注释,把最后的示例行改成你的命令即可:
interval=10
restart_on_success=0
log_dir=logs
# 下面这行换成你的命令
/svr/frpc/frpc -c /svr/frpc/frpc.toml
保存:nano 里按 Ctrl+O 再回车,然后 Ctrl+X 退出。
规则只有四条:
- 一行一条命令,行首行尾的空格会被忽略。
- 空行和
#开头的行不执行,可以拿来写注释。 - 命令行里不要写行内
#注释,#后面的字会被当成参数传给程序。 - 想给某一条单独设置重启间隔,在那一行末尾加
@15(15 秒)。
三个全局配置
services.conf 里只有下面三个键会被当成配置,其他任何 key=value 都会被当成命令去执行——这是新手最容易踩的坑。
| 键 | 作用 | 默认值 | 新手怎么填 |
|---|---|---|---|
interval | 命令退出后等多少秒再拉起 | 3 | 写 10。别写 0,脚本会按 0.5 秒算,崩溃时会疯狂重启 |
restart_on_success | 退出码为 0(正常退出)时是否也重启 | 0 | 保持 0。要做定时任务才写 1 |
log_dir | 日志放哪个目录,相对配置文件所在目录 | logs | 写 logs 就行;用绝对路径也可以 |
第五步:启动 multi_runner,看日志
cd /svr/frpc
python3 multi_runner.py
它会占用当前终端,把所有命令拉起来。先别关这个终端,看到这样的输出就说明起来了:
[2026-10-23 23:10:02] [svc#0] 已启动 pid=12345: /svr/frpc/frpc -c /svr/frpc/frpc.toml
另开一个 SSH 窗口看日志:
ls -l /svr/frpc/logs
tail -f /svr/frpc/logs/00_frpc.log
日志文件名是「两位序号_程序名.log」,序号就是它在 services.conf 里的顺序(从 00 开始)。所以第一条 frpc 命令对应 00_frpc.log。
tail -f 里按 Ctrl+C 只是停止跟踪日志;要停掉服务,回到运行 multi_runner.py 的那个窗口再按一次 Ctrl+C。
脚本默认读「脚本同目录的 services.conf」,也可以把路径当参数传进去,例如 python3 multi_runner.py /etc/frpc/services.conf。这样一台机器可以放多份配置,各跑各的。
窗口一关、SSH 一断,multi_runner.py 和它拉起的 frpc 通常会一起退出,机器重启更不会自动起来。所以还差最后一步。
第六步:交给 systemd 守住(强烈建议)
sudo nano /etc/systemd/system/multi_runner.service
[Unit]
Description=multi_runner (frpc 等多服务守护)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=/svr/frpc
ExecStart=/usr/bin/python3 /svr/frpc/multi_runner.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
三个地方按实际改:
ExecStart里的/usr/bin/python3:用which python3查到的路径;multi_runner.py:写绝对路径;WorkingDirectory:不能省。脚本按「运行它时的当前目录」启动命令,-c frpc.toml这类相对路径全指望它。(log_dir是另一套规则:相对路径按配置文件所在目录算。)
然后让它生效并开机自启:
sudo systemctl daemon-reload
sudo systemctl enable --now multi_runner
sudo systemctl status multi_runner --no-pager
看到 Active: active (running) 就成了。
改完怎么生效
| 你改了什么 | 执行什么 | 影响 |
|---|---|---|
services.conf | sudo systemctl restart multi_runner | 所有命令重启一次,会短暂断线 |
frpc.toml | sudo systemctl restart multi_runner | 同上 |
multi_runner.py | sudo systemctl restart multi_runner | 同上 |
multi_runner.service | sudo systemctl daemon-reload 然后 restart | 改了服务文件必须先重载 |
multi_runner 没有单条重启的命令。最常见的做法是直接 restart 全部(一般几秒)。如果某条特别不能断,把那条单独拆成 systemd 服务,用教程二的方式托管。
启动、停止、看状态
| 目的 | 命令 |
|---|---|
| 启动 | sudo systemctl start multi_runner |
| 停止(连同它拉起的 frpc) | sudo systemctl stop multi_runner |
| 重启 | sudo systemctl restart multi_runner |
| 开机自启 | sudo systemctl enable multi_runner |
| 取消开机自启 | sudo systemctl disable multi_runner |
| 看状态 | sudo systemctl status multi_runner --no-pager |
| 看脚本自己的日志 | sudo journalctl -u multi_runner -n 50 --no-pager |
| 看每个服务的日志 | ls /svr/frpc/logs/,再 tail -f 对应文件 |
stop 之后如果 ps -ef | grep frpc 还能看到残留进程,说明有子进程跑出了进程组,去看高手版「进程、信号与退出码」一节。
只有一种情况:所有命令都「正常结束且不再重启」(退出码 0 且 restart_on_success=0)。如果配上 Restart=always,systemd 会把它再拉起来,等于重新启动一轮。frpc 常驻时不退出,不用管这条。
常用写法:直接抄
| 你要的效果 | 在 services.conf 里写 |
|---|---|
| 跑一个 frpc(配置文件方式) | /svr/frpc/frpc -c /svr/frpc/frpc.toml |
| 跑一个 frpc(面板命令方式) | /svr/frpc/frpc -u 你的用户令牌 -p 你的隧道ID |
| 先切目录再启动 | bash -c 'cd /svr/frpc && exec ./frpc -c frpc.toml' |
| 单独设置这一条的重启间隔 | 在行尾加 @15 |
| 设置时区 | bash -c 'export TZ=Asia/Shanghai; exec /svr/frpc/frpc -c /svr/frpc/frpc.toml' |
| 再跑第二条隧道 | 再加一行,把 frpc.toml 换成第二个配置文件 |
表格里的写法都可以直接粘,但令牌、隧道 ID、路径要换成你自己的。
新手最容易写错的 7 行
| 你可能写成 | 实际会发生什么 | 改成 |
|---|---|---|
cd /svr/frpc && ./frpc -c frpc.toml | cd 被当成程序名,找不到,无限重启 | bash -c 'cd /svr/frpc && exec ./frpc -c frpc.toml' |
TOKEN=xxx ./frpc -c frpc.toml | 把 TOKEN=xxx 当成程序名,无限重启 | bash -c 'export TOKEN=xxx; exec ./frpc -c frpc.toml' |
./frpc -c frpc.toml # 家里的隧道 | # 和后面几个字都变成 frpc 的参数 | 注释单独占一行,或整条包进 bash -c |
./frpc -c frpc.toml & | & 变成参数;在 bash -c 里还会让脚本以为服务已结束 | 去掉 &,让脚本自己守 |
没 chmod +x 就写进 services.conf | 权限不足,无限重启 | 先 chmod +x /svr/frpc/frpc |
./frpc -c frpc.toml 但当前目录不对 | 找不到 frpc.toml | -c 后面写绝对路径 |
在 bash -c '...' 里又套单引号 | 引号提前结束,命令被拆乱 | 内层改用双引号 |
最后一条的典型例子,这样写很难读也容易错:
bash -c 'cd /svr/frpc && exec ./frpc -c '"'"'frpc.toml'"'"''
直接写成:
bash -c 'cd /svr/frpc && exec ./frpc -c "frpc.toml"'
出问题了,按这个顺序查
- 服务在不在跑:
sudo systemctl status multi_runner --no-pager,看Active:是不是active (running)。 - 脚本自己有没有报错:
sudo journalctl -u multi_runner -n 50 --no-pager。 - 业务日志:
ls -l /svr/frpc/logs/,再tail -n 50对应文件。 - 把命令复制出来手动跑:报错直接显示,比看循环重启的日志快得多。
日志里出现这些词,对应的通常是:
| 日志里的词 | 说明 | 怎么办 |
|---|---|---|
命令解析失败 | 引号没闭合,这一行被整行跳过 | 检查单引号、双引号是否成对 |
中没有可执行的命令 | services.conf 里只有注释,没有命令 | 按第四步加一行命令,再 restart |
无法打开日志文件 | log_dir 指向的目录不可写 | 改回 log_dir=logs,或给目录写权限 |
Permission denied | 没有执行权限 | chmod +x |
No such file or directory | 路径写错,或工作目录不对 | 全部改成绝对路径 |
connection refused | 本机服务没起来,或端口写错 | 先手动访问内网地址确认 |
| 每隔几秒重启一次 | 命令本身在秒退 | 手动跑,看它退出前的报错 |
「systemctl status 的最后 20 行」+「logs/ 里对应文件的最后 50 行」,基本就能定位。只发一句「起不来」,谁也猜不到。
到这里就够了
记住三句话:
- 命令写绝对路径;
- 需要
cd、&&、变量、管道的,整条包进bash -c '...'; - 改完
services.conf就systemctl restart multi_runner。
下面高手版把这三句话背后的规则全部讲清楚。
教程一 · 高手版(深度解析 Shell 语法与脚本行为)
下面这一份讲的是脚本内部怎么解析、什么会坏、为什么坏。不影响你把服务跑起来;日常排错时按目录跳到对应小节即可。
先看第一节的「解析链路总览」,建立「配置文件 → 分词 → exec」这三层的印象;再按需要查后面的规则。第六、第八节是排错时翻得最多的。
一、解析链路总览
一条配置行从文件到真正执行,要经过三层处理,任何一层出错都会导致"命令看起来对、就是起不来":
配置文件一行
│
├─ 第 1 层:行级规则(本脚本) 去空白 / 跳空行 / 跳 # 注释行 / 剥离尾部 @N / 识别全局配置行
│
├─ 第 2 层:shlex 分词(本脚本) 按 POSIX 规则切分成参数列表;不是 shell,不展开任何东西
│
└─ 第 3 层:内核 exec(Popen) 直接执行列表第 1 项;只有显式写 bash -c 时才进入真正的 shell 语义
关键结论:本脚本默认不经过 shell。第 2 层只是"把字符串切成参数数组",它不做变量展开、不做通配符展开、不解释 && | ; > () cd ~ $。所有 shell 语法都必须通过 bash -c '...' 显式引入。
二、第 1 层:行级规则
2.1 空行与注释
- 整行
strip()后为空 → 跳过。 - 整行
strip()后以#开头 → 跳过。 - 行内
#不是注释。./frpc -c frpc.ini # 备注会把#和备注作为两个参数传给 frpc。只有全局配置行的值部分例外(值里#之后被截掉)。
# 这是注释,正确
./frpc -c frpc.ini # 这不是注释,# 和"这不是注释"会成为参数
需要行内注释时用 bash -c:
bash -c './frpc -c frpc.ini # 备注'
2.2 全局配置行
形如 key=value 且 key 属于 interval / restart_on_success / log_dir 三者的行,被当作配置,不当命令。其他 key=value(如 FOO=bar cmd)不会被识别为配置,会继续走到第 2 层,然后因 FOO=bar 不是可执行文件而启动失败、无限重试。参见第八节陷阱。
2.3 尾部 @N 重启间隔
正则 ^(.*\S)\s+@([0-9]+(?:\.[0-9]+)?)\s*$:行尾"空白 + @ + 数字"会被剥离,作为该命令独立的重启间隔。
./frpc -c frpc.ini @10 # 间隔 10s,命令是 ./frpc -c frpc.ini
bash -c 'cd /x && exec ./y' @5 # 间隔 5s,引号内的内容不受影响
会误伤的情况:命令本身以"空格 + @数字"结尾,例如参数是 @123:
./app --token @123 # 被误判:命令变成 ./app --token,间隔 123 秒
规避:包进 bash -c,因为整行结尾是引号,正则不匹配:
bash -c './app --token @123'
2.4 未闭合引号
第 2 层 shlex.split 遇到未闭合引号抛 ValueError,脚本打印警告并跳过该行(不是无限重试)。排查时先看启动日志有没有 命令解析失败。
三、第 2 层:shlex 分词规则
shlex.split(s)(POSIX 模式)做的事只有一件:按 shell 的词法规则把字符串切成 argv 数组。它和真正的 shell 共享"引号与转义"部分,但不共享"展开与语法"部分。
3.1 空白分隔
空格、Tab 分隔参数,连续空白视为一个。换行不在一行内出现。
3.2 反斜杠(引号外)
转义下一个字符,使特殊字符变字面量:
./app a\ b → ["…/app", "a b"] 一个参数
./app \"x\" → ["…/app", '"x"']
常用于含空格的文件名、需要字面 # @ ' " 的场景。
3.3 单引号
内部一切字面,包括 $ \ " ` && | > # @ 空格。不能包含单引号本身(要包含就结束单引号、写 \'、再开单引号,见第五节)。
bash -c 'echo $HOME && ls *.log' # 整段是一个参数交给 bash
3.4 双引号
内部保留空白和大多数特殊字符,但反斜杠仍部分生效:\" → ",\\ → \,其余 \x 按字面保留 \x。不做变量展开(shlex 不是 shell)。
bash -c "cd /volume1/frp && exec ./frpc -c frpc.ini"
3.5 引号拼接
相邻的引号段与裸字拼接成一个参数:
a'b c'd → ["ab cd"]
"x"'y' → ["xy"]
3.6 shlex 不做的六件事
| 写法 | shlex 结果 | 说明 |
|---|---|---|
*.log | 字面 *.log | 通配符不展开 |
$HOME | 字面 $HOME | 变量不展开 |
~ | 字面 ~ | 波浪号不展开 |
$(date) / `date` | 字面 | 命令替换不执行 |
a && b | 三个参数 a && b | && 只是普通 token |
a > f 2>&1 | 参数 a > f 2>&1 | 重定向不生效 |
凡是上表出现的东西,都必须放进 bash -c '...' 里才有 shell 语义。
四、第 3 层:什么时候必须进 shell
只要命令里出现下列任一元素,就必须用 bash -c '...' 包裹,否则会失败或行为不符预期:
- 命令连接与逻辑:
;&&|| - 管道:
| - 重定向:
>>><2>&12>/dev/null<<< - 子 shell 与分组:
( ... ){ ...; } - 工作目录切换:
cdpushd - 变量赋值与展开:
VAR=x cmd、$VAR、${VAR:-默认} - 命令替换:
$(...)、反引号 - 通配符:
*?[a-z] - 波浪号展开:
~ - shell 内置命令:
exportsource.ulimitumaskwaittrap - 需要 shell 语法做行内注释
而下面这些不需要 shell,直接写即可(脚本原生支持):
- 绝对路径或已在 PATH 中的可执行文件 + 参数
- 参数中含空格(用单/双引号或反斜杠)
- 参数中含
#@=等非语法字符
五、bash -c 的引号工程
5.1 基本形式
bash -c '<shell 脚本内容>'
经过 shlex 后变成 ["bash", "-c", "<shell 脚本内容>"],再由 bash 自己解析第三段。这就是"把 shell 请回来"的唯一入口。
5.2 外层单引号(首选)
外层单引号最稳,因为 shlex 对它内部完全不做处理,内容原样传给 bash。
问题:shell 脚本内容里若需要单引号,单引号不能嵌套。解决办法是经典的 '\'' 四字符拼接——结束单引号、转义出一个单引号、再开单引号:
bash -c 'cd /volume1/frp && exec ./frpc -c '"'"'frpc.ini'"'"''
这种拼法很难看,所以外层单引号 + 内层用双引号是常规做法:
bash -c 'cd /volume1/frp && exec ./frpc -c "frpc.ini"'
bash -c 'cd /volume1/frp && exec ./frpc -c "my config.ini"'
5.3 外层双引号
当内容里需要大量单引号、且不含 $ ` " \ 时可用:
bash -c "cd /volume1/frp && exec ./frpc -c 'frpc.ini'"
注意 shlex 对双引号内反斜杠的处理,避免在双引号层写 \"、\\。
5.4 exec 的作用
bash -c 'cd /x && exec ./y' # 推荐
bash -c 'cd /x && ./y' # 可行,但不推荐
- 加
exec:bash 用y替换自己,PID 不变。本脚本记录的pid就是y的 pid;y的退出码直接成为这行的退出码;killpg杀到的是y所在进程组(含y的后代)。重启判定最准确。 - 不加
exec:bash 是父、y是子,同一进程组。killpg仍然能杀干净(因为start_new_session=True让 bash 成为新会话首进程,整组可杀),但脚本记录的 pid 是 bash 的,退出码是 bash 的(通常等于最后一条命令,但遇信号时可能不同)。能用,不如exec精确。
exec 只能用于"shell 脚本的最后一条命令",且不能用在管道左端或需要后续语句的位置(exec 会替换掉 shell,后面的语句不执行)。
5.5 多层嵌套
bash -c 里再套 bash -c 时,每层各用一套引号,从外到内交替:
bash -c 'bash -c "echo inner"'
一般不需要两层;出现两层说明可以用一层 + ; 或 && 简化。
六、Shell 语法逐项详解(对照本程序行为)
以下每条都给出"错误写法 → 实际发生什么 → 正确写法"。
6.1 命令序列 ;
chmod +x /svr/frpc/frpc ; /svr/frpc/frpc -c /etc/frpc.ini
错误:shlex 后 ; 是参数,chmod 会去改一个叫 ; 的文件,失败,脚本按间隔无限重试这个失败的 chmod。
正确:
bash -c 'chmod +x /svr/frpc/frpc; exec /svr/frpc/frpc -c /etc/frpc.ini'
6.2 逻辑与 && / 逻辑或 ||
cd /volume1/frp && ./frpc -c frpc.ini
错误:&& 被当参数,cd 是 shell 内置、系统中通常没有 /usr/bin/cd,Popen 直接 FileNotFoundError(或找到 /bin/cd 的极少数系统上行为古怪)。
正确:
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'
&& 语义:前一条成功(退出码 0)才执行后一条。需要"无论前一条成败都执行"用 ;;需要"前一条失败才执行"用 ||。
6.3 子 shell ( ... ) 与分组 { ...; }
一种常见写法:
(cd /volume1/frp && ./frpc -c frpc.ini)
错误:shlex 得到 ["(cd", "/volume1/frp", "&&", "./frpc", "-c", "frpc.ini)"],第 1 项 (cd 不是可执行文件,FileNotFoundError,无限重试。
正确:
bash -c '(cd /volume1/frp && exec ./frpc -c frpc.ini)'
但这里的 ( ) 没有必要,因为 bash -c 本身已经是独立 shell,cd 只影响这个 bash,不会污染本脚本或其他服务。bash -c 已经是天然的"子 shell 隔离"。只有在同一个 bash -c 脚本里需要"一段 cd 不影响后续语句"时才需要 ( ):
bash -c '(cd /a && exec ./one) & (cd /b && exec ./two) & wait'
{ ...; } 是分组,不创建子 shell,cd 会影响后续;注意 { 后要有空格、} 前要有 ;。
6.4 管道 |
./frpc -c frpc.ini | grep -v health
错误:| 是参数,frpc 收到额外三个参数,可能报错或被忽略。
正确:
bash -c 'exec ./frpc -c frpc.ini 2>&1 | grep --line-buffered -v health'
注意两点:
- 管道左端不能写
exec。exec会替换掉 bash 自己,右边grep就没人启动了。整条bash -c的退出码是管道最后一环(grep)的退出码——frpc 崩溃时 grep 仍可能返回 0,重启判定会失效。要守护崩溃,别在管道末端判活;或者用set -o pipefail;让管道任一环失败即整体失败:INIbash -c 'set -o pipefail; ./frpc -c frpc.ini 2>&1 | grep --line-buffered -v health' grep默认块缓冲,日志会延迟。加--line-buffered。
6.5 重定向
本脚本已经把子进程的 stdout 接到日志文件、stderr 合并进 stdout(stderr=subprocess.STDOUT)。命令里再写重定向会覆盖这个行为:
./frpc -c frpc.ini > /var/log/frpc.log 2>&1
错误:> 2>&1 是参数。正确:
bash -c 'exec ./frpc -c frpc.ini > /var/log/frpc.log 2>&1'
但这样日志就不写进本脚本的 logs/ 目录了,脚本的日志文件只剩空壳。通常没必要——直接用脚本的日志即可。唯一值得用的是丢弃输出:
bash -c 'exec ./noisy-app --quiet 2>/dev/null >/dev/null'
或只丢弃 stderr:
bash -c 'exec ./app 2>/dev/null'
注意 stdin 已被脚本接到 /dev/null,命令里的 < 重定向仍可覆盖它,但交互式命令整体不适合本脚本(见第八节)。
6.6 工作目录 cd
脚本没有暴露 cwd 配置,Popen 的 cwd 是运行脚本时的当前目录,不是配置文件所在目录,也不是命令里可执行文件所在目录。因此:
- 依赖相对路径配置文件(如
-c frpc.ini)时,必须cd。 - 不要依赖"脚本会切到命令所在目录"。
正确:
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'
或干脆用绝对路径,无需 shell:
/volume1/frp/frpc -c /volume1/frp/frpc.ini
能用绝对路径就不用 cd,少一层 shell、少一类引号问题。
6.7 变量赋值与展开
FOO=bar ./app
错误:shlex 得到 ["FOO=bar", "./app"],Popen 找名为 FOO=bar 的可执行文件,FileNotFoundError,且脚本会无限重试。这是最隐蔽的陷阱之一,因为命令行里这样写是完全合法的 shell 语法。
正确,两种:
env FOO=bar ./app # 用 env 命令,不需要 shell
bash -c 'export FOO=bar; exec ./app' # 需要 shell 时
引用变量:
bash -c 'exec ./app --home "$HOME" --conf "${CONF_DIR:-/etc/app}"'
注意外层单引号让 $HOME 原样到达 bash,由 bash 展开。若外层用双引号,shlex 虽不展开 $,但会处理反斜杠,容易出岔子——坚持单引号。
需要把脚本环境传入:
bash -c 'exec ./app --token "$FRPC_TOKEN"'
前提是运行 multi_runner.py 的那个 shell 里 export 了 FRPC_TOKEN,子进程继承环境。
6.8 命令替换 $(...)
bash -c 'exec ./app --start-time "$(date +%s)"'
`...` 等价但可读性差、易与引号冲突,优先 $()。
6.9 通配符
./app --conf /etc/app/*.conf
错误:* 原样传给程序。正确:
bash -c 'exec ./app --conf /etc/app/*.conf'
风险:匹配到多个文件时,程序会收到多个参数。需要精确时用 find/ls 在 shell 里处理,或直接写全路径。
6.10 波浪号 ~
./app --home ~/data
错误:~ 原样传入(Popen 不做展开,程序多半也不做)。正确:
bash -c 'exec ./app --home "$HOME/data"'
6.11 后台 & —— 禁止
./app &
错误且危险:& 是参数,shlex 后 Popen 执行 ./app 并把 & 当参数,./app 立即以前台方式运行——这时还能"碰巧"工作。但如果写的是 bash -c './app &':
bash -c立即返回 0,脚本认为该服务"正常结束、不再重启",./app变成孤儿进程,脚本退出后仍在跑,脚本的停止逻辑也管不到它(虽然同进程组killpg能杀到,但脚本在它退出前就已判定结束)。- 若
restart_on_success=1,会每隔 N 秒再起一个,进程越堆越多。
守护程序里永远不要写 &。脚本本身已经负责"启动、等待、重启",命令必须是前台常驻进程。
6.12 nohup / setsid / disown —— 禁止
同理,这些工具的目的是"脱离父进程独立存活",与本脚本"由我守护、由我停止"的模型冲突。脚本已用 start_new_session=True 处理进程组隔离,不需要 setsid。
6.13 source / .
bash -c '. /etc/profile; . /opt/app/env.sh; exec ./app'
用于加载环境脚本后再启动。
6.14 ulimit / umask
bash -c 'ulimit -n 65535; exec ./app'
bash -c 'umask 027; exec ./app'
这两条是 shell 内置,只能在 bash -c 里生效,影响该子进程及其后代。
6.15 trap —— 不推荐
脚本停止时向整个进程组发 SIGTERM。命令自己 trap 可以捕获并做清理,但若清理耗时长,脚本 5 秒后会 SIGKILL。简单清理可以,长清理不行。
七、进程、信号与退出码
理解这三者才能正确判断"会不会重启"。
7.1 重启判定
脚本只看 Popen.wait() 的返回码:
- 返回码 ≠ 0 → 异常 → 按间隔重启。
- 返回码 = 0 → 正常 →
restart_on_success=0时不再重启。 - 被信号杀死时返回码为负的信号编号(Python 语义),如
-9、-15,视为异常,会重启。
所以 bash -c 的退出码必须是"你关心的那个进程"的退出码。加 exec 时天然满足;不加 exec 时是 bash 脚本最后一条命令的退出码;用管道时默认是最后一环的退出码(用 pipefail 修正)。
7.2 进程组与停止
start_new_session=True 让每个服务成为新会话的首进程,之后 killpg(os.getpgid(pid), SIGTERM) 发给整组:
- 直接写命令:组里是目标进程及其后代,全部收到。
bash -c '... exec ...':exec 后组首就是目标进程,同样全部收到。bash -c '... | ...':组里是 bash 及其拉起的管道两侧所有进程,全部收到。
脚本停止流程:SIGTERM → 等 5 秒 → SIGKILL。
7.3 子进程清理
目标进程自己 fork 的子进程若不在同一进程组(比如自己又 setsid 了),脚本杀不到。避免在被守护的命令里再 setsid / daemonize。
八、陷阱清单
按踩坑概率排序:
&&;|直接写在配置里:被当参数,命令失败,无限重启。→bash -c。VAR=x cmd直接写:Popen 找名为VAR=x的文件,失败,无限重启。→env或bash -c。cd直接写:内置命令无对应可执行文件,失败,无限重启。→bash -c 'cd ... && exec ...'。- 行内
#:不是注释,成为参数。→ 删掉,或bash -c。 - 尾部
@N误伤:命令末尾"空格 +@数字"被当间隔。→ 包进bash -c。 - 单引号未闭合:整行被跳过(看日志有无"命令解析失败"),不会重启。
- 单引号嵌套单引号:外层单引号提前结束,后半段被 shlex 重新分词,行为错乱。→ 内层用双引号。
bash -c './app &':服务被判定立即正常结束,进程变孤儿。→ 去掉&。bash -c 'exec ./a | ./b':exec在管道左端无意义且破坏右侧启动。→ 左端不写exec,加pipefail。- 命令里重定向到自己的日志:脚本的
logs/xx.log变空壳,两套日志并存。→ 通常不需要重定向。 - 交互式命令(需要 stdin、需要 tty):
stdin已接/dev/null,必然失败或挂起。本脚本不适合跑交互程序。 - 用相对路径配置:工作目录是"运行脚本时的目录",不是配置文件目录。→ 绝对路径或
cd。 ./frpc但没chmod +x:PermissionError,无限重启。→ 启动前手动chmod +x一次。- 密码/令牌含 shell 特殊字符(
$!`\"):在双引号层会被处理。→ 用单引号层,或在单引号内用双引号包参数。 pipefail缺失:管道左侧崩溃被右侧掩盖,永不重启。→set -o pipefail。
九、场景配方
全部为可直接粘贴进 services.conf 的写法。
1. 最简单:绝对路径常驻进程
/svr/frpc/frpc -u 7ylySJuVtDt5rRCEv3ESIeD2 -p 339931
2. 需要特定工作目录、配置文件是相对路径
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'
3. 先 chmod 再启动(不推荐,推荐事先手动 chmod)
bash -c 'chmod +x /svr/frpc/frpc && exec /svr/frpc/frpc -u USER -p PORT'
4. 设置环境变量
bash -c 'export FRPC_LOG_LEVEL=info; export TZ=Asia/Shanghai; exec ./frpc -c frpc.ini'
或不需要 shell 时:
env TZ=Asia/Shanghai /svr/frpc/frpc -c /etc/frpc.ini
5. 提高文件描述符上限
bash -c 'ulimit -n 65535; exec /opt/app/server --port 9000'
6. 过滤日志后再交给脚本记录
bash -c 'set -o pipefail; exec 2>&1 | grep --line-buffered -v -E "health|ping"'
注意:这种写法里没有 exec 目标进程,见 6.4 的退出码问题。更稳的写法是让程序自己降噪,而不是在 shell 里过滤。
7. 丢弃全部输出
bash -c 'exec /opt/app/worker --quiet >/dev/null 2>&1'
8. 启动前等待依赖端口就绪
bash -c 'until nc -z 127.0.0.1 3306; do sleep 1; done; exec /opt/app/api --port 8080'
9. 单实例保护(防止上次残留进程)
bash -c 'exec flock -n /var/lock/frpc.lock /svr/frpc/frpc -c /etc/frpc.ini'
flock 拿不到锁立即失败退出(非 0),脚本会重启,直到锁释放——正好实现"等旧实例退出再拉起"。
10. 多命令顺序依赖,最后一条常驻
bash -c 'mkdir -p /var/run/app && chown app:app /var/run/app && exec runuser -u app -- /opt/app/server'
11. 参数含空格与特殊字符
bash -c 'exec /opt/app/server --name "my server" --token "a$b!c"'
外层单引号保证 $ ! 原样到达 bash,内层双引号保证空格不被拆开;bash 展开时双引号内 $b 仍会尝试展开——若令牌里真有 $,改用单引号内层:
bash -c 'exec /opt/app/server --name "my server" --token '\''a$b!c'\'''
这种多层引号极难维护,更简单的办法是把敏感参数放进环境变量或用配置文件:
bash -c 'exec /opt/app/server --name "my server" --token "$APP_TOKEN"'
12. 带独立重启间隔
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini' @10
13. 定时型"常驻"(程序秒退,需要它反复跑)
interval=60
restart_on_success=1
/opt/scripts/collect.sh
配合 restart_on_success=1,正常退出也会每 60 秒重跑,等价于简易定时器。
14. 需要以其他用户运行
bash -c 'exec setpriv --reuid=app --regid=app --init-groups /opt/app/server'
或 runuser -u app -- /opt/app/server(需要 root 启动脚本)。
十、速查表
| 需求 | 写法 |
|---|---|
| 普通命令 | 绝对路径 参数... |
| 换目录 | bash -c 'cd DIR && exec CMD' |
| 多命令串联 | bash -c 'A; exec B' 或 bash -c 'A && exec B' |
| 环境变量 | env K=V CMD 或 bash -c 'export K=V; exec CMD' |
| 管道 | bash -c 'set -o pipefail; A | B'(左端不 exec) |
| 丢弃输出 | bash -c 'exec CMD >/dev/null 2>&1' |
通配符/~/$() | bash -c 'exec CMD ...' |
| 单独重启间隔 | 行尾 @N |
| 正常退出也重启 | 全局 restart_on_success=1 |
| 行内注释 | 只能写进 bash -c '...' 内 |
| 禁止 | &、nohup、setsid、disown、交互式命令 |
教程二 · 用 systemd 托管 frpc
systemd 是 Linux 自带的「服务管家」:开机自动启动、进程退出后自动拉起、日志统一进 journalctl。frpc 是前台常驻程序,天生适合交给它。
前提:系统里要有 systemd(Debian、Ubuntu、CentOS 和大多数 NAS 发行版都有)。确认一下:
systemctl --version
能打印出版本号就行。如果提示 command not found,说明这套系统(或这个容器)没有 systemd,只能用教程一的 multi_runner。
| 版本 | 内容 | 适合 |
|---|---|---|
| 新手版 | 一份能直接用的 frpc.service,标出只需要改的两行,附一键部署脚本 | 第一次写 systemd 服务 |
| 高手版 | Type=、Restart=、依赖排序、环境变量、模板单元、安全加固 | 要排查「为什么不重启 / 为什么不自启」 |
nohup ./frpc ... & 只能让程序在 SSH 断开后活着,机器重启就没了,进程崩了也不会自己回来。它适合临时测试,不适合长期放着。长期跑就用本文的 systemd 方式。
教程二 · 新手版(只教怎么写、怎么改)
下面这份模板来自教程原文,路径以 NAS 上的 /volume1/frp/frp3 为例,换成你自己的目录即可。
原文示例里写的是 frpc.ini。0.70.1 的压缩包给的是 frpc.toml(空文件),所以要改两处:
ExecStart里-c后面写frpc.toml;- 一键脚本里的
CONF=frpc.ini改成CONF=frpc.toml。
两种文件只是格式不同,-c 的用法完全一样。
一个 frpc 的 service 文件长什么样
把下面这段内容保存到 /etc/systemd/system/frpc.service,就是一个最小可用的 frpc 守护服务:
[Unit]
Description=ChmlFrp Client
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=/volume1/frp/frp3
ExecStart=/volume1/frp/frp3/frpc -c /volume1/frp/frp3/frpc.ini
Restart=always
RestartSec=15s
[Install]
WantedBy=multi-user.target
全文只需要你改 两行,其他原样保留:
WorkingDirectory=改成 frpc 所在的目录;ExecStart=改成 frpc 可执行文件的绝对路径,-c后面改成配置文件的绝对路径。
如果配置文件叫 frpc.toml 而不是 frpc.ini,只改 -c 后面那个文件名即可。
每个字段是干什么的(只说你用得上的)
[Unit] 段
Description:给人看的服务描述,不影响运行。After=network-online.target:告诉 systemd,等网络真正“就绪”后再启动 frpc。network.target只表示网络管理栈已启动,不保证接口已有可路由地址;network-online.target才是“网络已经可用”的同步点,对于 frpc 这种必须连外网的客户端,用后者更稳妥。Wants=network-online.target:把network-online.target主动拉进启动链。After只规定顺序,Wants才决定是否真的等它。
[Service] 段
Type=simple:最常用的启动类型,表示ExecStart启动的那个进程本身就是服务主进程,不会 fork 到后台。frpc 在前台运行,所以用它。WorkingDirectory:设置进程的当前工作目录(cwd)。frpc 如果使用相对路径找证书、日志或其他文件,全靠这个字段。service 文件里不能用cd,工作目录只能通过这个字段指定。ExecStart:启动命令。这里只能写“可执行文件 + 参数”,不能写cd ... && ...,不能写 shell 语法。所有路径都必须是绝对路径。Restart=always:无论进程是正常退出(exit 0)、异常退出(非零退出码)、被信号杀死,还是超时,systemd 都会重启它。RestartSec=15s:每次重启前等待 15 秒。这个值不宜太小,否则崩溃循环会给系统带来压力。
[Install] 段
WantedBy=multi-user.target:systemctl enable时,systemd 会在这个 target 下创建符号链接,从而实现开机自启。
有需求时怎么改
需求:frpc 崩溃后马上重启,不要等。
→ 把 RestartSec=15s 改成 RestartSec=3s 或 5s。
需求:只在异常退出时重启,正常退出就不管。
→ 把 Restart=always 改成 Restart=on-failure。这样 exit 0 不会触发重启,只有非零退出或被信号杀掉才重启。
需求:以非 root 用户运行 frpc。
→ 在 [Service] 段加两行:
User=frp
Group=frp
前提是该用户对 WorkingDirectory 和配置文件有读权限,对 frpc 二进制有执行权限。
需求:清理某个环境变量(比如之前遇到的 GODEBUG)。
→ 在 [Service] 段加:
UnsetEnvironment=GODEBUG
如果 systemd 版本不支持,改成 Environment="GODEBUG=" 也能达到置空的效果。
需求:限制 frpc 的内存占用。
→ 加 MemoryMax=256M(超出立即 OOM 杀掉本服务)或 MemoryHigh=200M(软限制,超过后尽量回收)。systemd 通过 cgroup 做限制,比 ulimit 更可靠。
改完之后必须做什么
只改配置不重启:systemctl restart frpc。
改了 service 文件本身:必须先 systemctl daemon-reload,否则修改被忽略。然后 systemctl restart frpc。
标准安全顺序:
systemctl daemon-reload && systemctl restart frpc && systemctl status frpc --no-pager
日常管理命令速查
| 目的 | 命令 |
|---|---|
| 查看当前状态 + 最近日志 | systemctl status frpc --no-pager |
| 启动 | systemctl start frpc |
| 停止 | systemctl stop frpc |
| 重启 | systemctl restart frpc |
| 重载 service 文件 | systemctl daemon-reload |
| 开机自启(仅下次开机生效) | systemctl enable frpc |
| 开机自启 + 立即启动 | systemctl enable --now frpc |
| 取消开机自启 | systemctl disable frpc |
| 查看完整日志 | journalctl -u frpc -n 50 --no-pager |
| 实时跟踪日志 | journalctl -u frpc -f |
enable 和 start 是两条独立的轴:enable 只管下次开机是否自动启动,不启动当前;start 只管现在启动,不影响开机行为。“测试时能跑,重启后丢了”几乎都是只 start 没 enable 导致的。
一键部署(新手直接整段粘贴)
把 FRP_DIR 和配置文件名改成你的实际情况,整段粘贴到 root 终端:
FRP_DIR=/volume1/frp/frp3
CONF=frpc.ini
cat > /etc/systemd/system/frpc.service <<EOF
[Unit]
Description=ChmlFrp Client
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=${FRP_DIR}
ExecStart=${FRP_DIR}/frpc -c ${FRP_DIR}/${CONF}
Restart=always
RestartSec=15s
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now frpc && systemctl restart frpc && sleep 2 && systemctl status frpc --no-pager
如果之前已经有一个同名服务在跑,先 systemctl stop frpc 再执行,避免旧进程残留。
改完 frpc.service 一定要 sudo systemctl daemon-reload,只 restart 不会重新读文件。原文已经写了,这里再强调一次——「改了没生效」九成是漏了它。
/svr/frpc/frpc verify -c /svr/frpc/frpc.toml
看到 syntax is ok 再 systemctl restart frpc,能少一次「重启完才发现配置写错」。
教程二 · 高手版(systemd 到底怎么执行你的 service)
这一部分解释 systemd 的进程模型:ExecStart 为什么不走 shell、Restart= 什么时候会失效、enable 和 start 为什么是两件事。排查「开机没起来」「崩了不重启」时按节查。
第一次读可以只看每节的第一段和代码块;2.3(进程模型)、2.4(环境变量)、2.9(编辑与重载)是排错时最常用的三节。
2.1 先理解 systemd 的“视角”和你手动 Shell 的根本区别
你在终端里执行 ./frpc -c frpc.ini,背后有一个交互式 Shell 负责解析 &&、cd、通配符、环境变量展开。ExecStart= 不经过 Shell(除非你显式写 /bin/sh -c '...',但这通常会引入额外的进程层级和信号语义问题)。systemd 直接把 ExecStart 按空白切分成 argv,然后 execve 第一个参数作为可执行文件。所以:
(cd /x && ./y)会被当成“可执行文件名是(cd”;~不展开;$VAR不展开(除非用 systemd 自己的环境变量机制);- 所有路径必须是绝对路径。
这不是 systemd“不支持 Shell”,而是它有意避免 Shell 带来的不确定性和额外进程层级。工作目录、环境、用户、权限、资源限制,全部由 systemd 在 execve 之前或通过 cgroup 施加。
2.2 [Unit] 段:依赖与排序语义
After= 和 Before= 是排序约束,只规定“谁先谁后”,不保证对方一定被启动。Wants= 和 Requires= 是依赖约束:Wants 是弱依赖,对方启动失败不影响本服务继续启动;Requires 是强依赖,对方失败本服务也失败。
对于 frpc 这种网络客户端,推荐组合是:
After=network-online.target
Wants=network-online.target
network.target 在启动阶段的语义很弱:它只表示网络管理栈已启动,此时接口是否已配置、是否已有可路由地址并不确定;它真正可靠的语义在关机阶段(保证在关机时先停掉依赖网络的服务)。network-online.target 才是“网络已经可用”的同步点,它会主动等待网络管理软件报告“上线”。对于“开机后必须立即连上服务端”的 frpc,后者更合适。
但官方文档也提醒:不要滥用 network-online.target。它主要面向没有网络就无法工作的客户端软件;服务端软件通常不需要等网络完全 online 才能接受本地连接。frpc 属于典型客户端,所以用它是合理的。
2.3 [Service] 段:进程模型与生命周期
Type= 决定 systemd 怎么判断“启动完成了”。
simple:ExecStart的进程就是主进程,systemdfork后立即认为启动完成,然后监督这个 PID。frpc 在前台阻塞运行,属于这一类。exec:和simple类似,但 systemd 会等到execve成功后才认为启动完成。如果你希望“二进制路径写错时立即报 failed 而不是短暂 active 再挂掉”,可以用exec。forking:传统 daemon 自己fork到后台、父进程退出,需要配合PIDFile=跟踪主进程。frpc 不 fork,所以不用。notify:程序通过sd_notify()主动告诉 systemd “我准备好了”。frpc 不支持,用了只会卡住或超时。oneshot:适合“执行一次就结束”的脚本,不适合常驻进程。
Restart= 的精确语义:
always:无论退出状态如何都重启,包括exit 0、非零退出、被信号杀死、超时。on-failure:只有非零退出码、被信号杀死、超时等“非干净退出”才重启;exit 0不重启。no(默认):不自动重启。
Restart=always 有一个容易被忽略的细节:systemd 默认有启动频率限制。如果在短时间内反复崩溃,达到 StartLimitBurst(默认 5 次 / StartLimitIntervalSec 默认 10 秒)后,systemd 会放弃重启并标记为 failed。如果你确实希望“无论如何都一直拉起”,需要在 [Unit] 段显式放宽限制:
StartLimitIntervalSec=0
设为 0 表示禁用启动频率限制。否则一个持续秒退的 frpc 可能在几次重启后被 systemd 彻底放弃。
RestartSec= 只控制两次重启之间的睡眠时间,与 Restart= 配合使用。设得太短(如 0)会让崩溃循环迅速触发频率限制;设成 15s 可以在“及时恢复”和“给系统喘息”之间取得平衡。
WorkingDirectory= 在 execve 之前通过 chdir() 设置进程 cwd。它影响 frpc 内部所有相对路径的解析。即使 ExecStart 和 -c 都用了绝对路径,某些 frpc 内部逻辑(如证书、日志、临时文件)仍可能依赖 cwd,所以这个字段不是“可选的装饰”,而是确定进程行为的一部分。
ExecStart= 的前缀语义(高手会用到但新手通常不需要):
-前缀:忽略该命令的非零退出码;@前缀:第二个参数作为argv[0];+/!前缀:以完整权限执行,绕过User=/ 沙箱限制;:前缀:不执行,只做环境变量赋值。
这些前缀是 systemd 特有的 mini-language,不属于 Shell。在 frpc 场景下通常不需要,但排查别人写的 unit 时值得知道。
2.4 环境变量与 UnsetEnvironment
systemd 的服务环境不继承你登录 Shell 的环境。它从 DefaultEnvironment=、Environment=、EnvironmentFile= 以及 systemd 自身的管理环境构建。之前遇到的 GODEBUG=tlskyber=0 fatal,就是 systemd 启动环境中存在该变量,而新版 Go 运行时拒绝这个旧值。
UnsetEnvironment=GODEBUG 的语义是在 execve 之前从环境中删除这个变量,而不是置空。置空(Environment="GODEBUG=")在某些程序里仍然会被视为“存在但为空”,而删除才是彻底消除。对于 Go 运行时这类对“变量是否存在”敏感的程序,优先用 UnsetEnvironment=。
如果想查看 systemd 实际传给 frpc 的环境:
systemctl show frpc -p Environment
注意这显示的是 unit 配置层面的环境,不包括 systemd 管理器自身携带的变量。要查看进程实际环境,可以读取 /proc/<pid>/environ(需要 root)。
2.5 [Install] 段与 enable 的真实机制
WantedBy=multi-user.target 不是一个“命令”,而是声明“当 multi-user.target 被拉入启动链时,本服务也应当被拉入”。systemctl enable frpc 会在 /etc/systemd/system/multi-user.target.wants/ 下创建一个指向 frpc.service 的符号链接。开机时,systemd 解析 target 的 wants 依赖,从而拉起 frpc。
enable 和 start 完全解耦:
enable+ 不start:下次开机会启动,但现在不启动;start+ 不enable:现在运行,但重启后消失——这是“测试正常、重启失效”的头号原因。
systemctl enable --now 是两者的原子组合,适合一键部署。
2.6 验证、调试与依赖分析
静态验证 unit 语法:
systemd-analyze verify /etc/systemd/system/frpc.service
它会在不启动服务的情况下检查指令是否合法、可执行文件是否存在、依赖是否有明显问题。
查看启动链和耗时:
systemd-analyze critical-chain frpc.service
它会显示从 default.target 到 frpc.service 的完整依赖路径,以及每一步是否成功、耗时多少。如果 frpc 启动被 network-online.target 拖慢,这里会直接暴露出来。
查看依赖图:
systemd-analyze plot > deps.svg
生成全系统启动时序图(需要 graphviz),适合排查“为什么 frpc 在某个服务之前/之后启动”。
日志的权威来源:systemctl status 只显示最近几行且会被省略。完整原因永远在:
journalctl -u frpc.service --no-pager -n 100
关注 Main PID、status=、code=exited, status=203/EXEC(可执行文件找不到或不可执行)、Failed at step EXEC(execve 失败)等字段。203/EXEC 几乎总是路径错误、权限不足,或 ExecStart 里写了 shell 语法。
2.7 模板单元与多实例(frpc 的进阶用法)
如果一台机器需要跑多个 frpc 实例(不同配置、不同服务端),不需要复制多份 service 文件。用模板单元:
[Unit]
Description=ChmlFrp Client (%i)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=/volume1/frp/%i
ExecStart=/volume1/frp/%i/frpc -c /volume1/frp/%i/frpc.ini
Restart=always
RestartSec=15s
[Install]
WantedBy=multi-user.target
%i 是实例名。启动:
systemctl enable --now frpc@frp3
systemctl enable --now frpc@frp4
systemd 会用 frp3、frp4 填充 %i,分别使用 /volume1/frp/frp3/ 和 /volume1/frp/frp4/ 下的二进制和配置。模板单元是 systemd 处理“同一程序多实例”的标准方式,比复制粘贴 N 份 unit 文件更可维护。
2.8 安全加固(高手按需启用)
frpc 通常不需要 root 全权限。在 [Service] 段可以逐步收紧:
User=frp
Group=frp
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/volume1/frp/frp3
NoNewPrivileges=true:禁止进程通过setuid等方式提权;ProtectSystem=strict:把/usr、/boot等设为只读,/etc也受限;ProtectHome=true:隐藏/home、/root;PrivateTmp=true:给进程独立的/tmp;ReadWritePaths=:在strict模式下显式放开 frpc 需要写的目录。
这些指令不会改变 frpc 的业务逻辑,但会限制它“万一被攻破能做什么”。生产环境建议在功能验证通过后逐项加入,用 systemd-analyze security frpc.service 查看当前 unit 的安全评分和剩余暴露面。
2.9 编辑与重载的精确规则
- 只改
frpc.ini/frpc.toml:systemctl restart frpc。不需要daemon-reload。 - 改了
frpc.service文件内容:systemctl daemon-reload必须执行,否则 systemd 内存中仍然是旧 unit。daemon-reload只重读 unit 定义,不重启服务;要让新定义作用于正在运行的进程,还需要systemctl restart frpc。 - 新增或删除了 unit 文件:
daemon-reload同样必须。 systemctl reload frpc:要求服务自身支持“重载配置而不中断连接”(frpc 通过信号或内部机制支持时才有效),不要把它和restart混用。daemon-reload重载的是 systemd 管理器对 unit 文件的认知,reload重载的是服务进程自己的配置,两者不是一回事。
安全的编辑命令:
systemctl edit --full frpc
它会用 $EDITOR 打开完整 unit 文件,保存后自动触发 daemon-reload(取决于 systemd 版本),比手动 cat > 再 daemon-reload 少一步遗漏风险。
2.10 一键部署脚本的工程化写法
新手版给的是“改两行就粘贴”的版本。高手版的一键脚本应该具备幂等、前置校验、失败早退:
#!/usr/bin/env bash
set -euo pipefail
SERVICE=frpc
FRP_DIR=/volume1/frp/frp3
FRPC="${FRP_DIR}/frpc"
CONF="${FRP_DIR}/frpc.ini"
UNIT="/etc/systemd/system/${SERVICE}.service"
# 前置校验
[[ -x "$FRPC" ]] || { echo "frpc 不存在或不可执行: $FRPC" >&2; exit 1; }
[[ -f "$CONF" ]] || { echo "配置文件不存在: $CONF" >&2; exit 1; }
command -v systemctl >/dev/null || { echo "systemctl 不可用" >&2; exit 1; }
# 写入 unit
cat > "$UNIT" <<EOF
[Unit]
Description=ChmlFrp Client
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=${FRP_DIR}
ExecStart=${FRPC} -c ${CONF}
Restart=always
RestartSec=15s
[Install]
WantedBy=multi-user.target
EOF
# 验证语法(可选但推荐)
systemd-analyze verify "$UNIT" || true
# 生效
systemctl daemon-reload
systemctl enable --now "$SERVICE"
systemctl restart "$SERVICE"
systemctl --no-pager --full status "$SERVICE"
关键点:set -euo pipefail 让任何一步失败都立刻退出;[[ -x "$FRPC" ]] 和 [[ -f "$CONF" ]] 在写入 unit 之前拦截最常见的两类错误(路径不对、权限不对);systemd-analyze verify 在重载前做静态检查,避免把语法错误带进正在运行的系统。
如果部署的是多个实例,把 service 名改成 frpc@${INSTANCE},其余逻辑不变。
两个部分共同指向的一条底线
无论新手还是高手,frpc 的 service 能否稳定工作,最终取决于三件事:ExecStart 只写可执行文件和参数、工作目录用 WorkingDirectory 而不是 cd、改了 unit 文件必须 daemon-reload 再 restart。新手版把这三条包进可粘贴的模板里,高手版把这三条放回 systemd 的进程模型和依赖语义中去解释——目的都是让 frpc 从“在终端里能跑”变成“由系统可靠托管”。
旧版教程(0.50 系列 · 存档保留)
下面这一部分是原 frpc技术文档_2.html 的完整内容,对应 ChmlFrp 0.50 系列(示例压缩包为 0.51.2_251023)。原文保留,只做了三类修正:
- 代码块在网页上被压成一行的问题,已还原成正常换行;
- 几处会让人误判的文字已改正(例如把
ldd的结果当成缺库); - 补了少量「当时没写、现在会卡住新手」的说明,统一用「整理注」标出。
| 项目 | 旧版(本部分) | 新版(第一部分) |
|---|---|---|
| 配置文件 | frpc.ini(INI) | frpc.toml(TOML) |
| 启动参数 | -u 用户ID -p 隧道ID | -u 用户令牌 -p 隧道ID |
| 守护方式 | nohup 或 systemd | multi_runner 或 systemd |
两版的操作思路(上传、解压、赋权、systemd 托管)是一样的,但配置文件格式和参数含义不同。新机器请直接看第一部分;本部分留着,是给旧机器、旧配置对照用的。
1. 环境与前置条件
- 操作系统:Debian GNU/Linux 12 (bookworm)
- CPU 架构:ARM 32 位(
armv7l)或 64 位(aarch64) - 软件包:
ChmlFrp-0.51.2_251023_linux_arm.tar.gz - 权限:已通过 SSH 登录,具有
sudo权限
先执行 uname -m:x86_64 对应 linux_amd64,aarch64 对应 linux_arm64,armv7l 对应 linux_arm。架构下错的典型现象是「文件在、权限也给了,一执行就报 Exec format error」。
2. 文件上传与解压
2.1 上传文件到 NAS
任选一种方式。
方式一:WinSCP
协议选 SFTP,主机填 NAS IP,端口 22,拖拽上传。
方式二:SCP 命令(Windows 命令提示符)
scp -P 22 C:\本地路径\ChmlFrp-0.51.2_251023_linux_arm.tar.gz 用户名@NAS_IP:/home/用户名/
方式三:SMB 共享
在 Windows 运行 \\NAS_IP,复制粘贴到共享文件夹,再通过 SSH 移动到目标目录。
2.2 解压压缩包
tar -xzvf ChmlFrp-0.51.2_251023_linux_arm.tar.gz
解压后会得到一个与压缩包同名的目录,先进入目录再操作:
cd ChmlFrp-0.51.2_251023_linux_arm
目录里包含 frpc(主程序)、frpc.ini(配置文件模板)等。
2.3 添加执行权限
chmod +x frpc
3. 临时后台运行(使用 nohup)
此方式使程序在 SSH 断开后继续运行,但重启后不会自动启动,适合短期测试。
nohup ./frpc -u 你的用户ID -p 你的隧道ID > frpc.log 2>&1 &
-u和-p参数请替换为实际值。- 日志输出到当前目录的
frpc.log文件。
查看实时日志:
tail -f frpc.log
按 Ctrl+C 退出日志查看。
0.70.1 里 -u 传的是用户令牌、-p 传的是隧道 ID 列表,和这里写的「用户 ID」不是一回事。旧版参数以旧版面板为准,新版请看第一部分。
4. 配置为 Systemd 服务(开机自启 + 崩溃自动重启)
将程序托管给系统服务管理器,实现开机自启和异常退出后自动重启。
4.1 创建服务文件
服务文件位于 /etc/systemd/system/frpc.service,需使用 sudo 权限创建。
方式 A:nano 编辑器(若已安装)
sudo nano /etc/systemd/system/frpc.service
输入内容后按 Ctrl+O 保存,Ctrl+X 退出。
方式 B:vim 编辑器(系统自带)
sudo vim /etc/systemd/system/frpc.service
按 i 进入插入模式,输入内容。完成后按 Esc,输入 :wq 保存退出。
4.2 服务文件内容
[Unit]
Description=ChmlFrp Client
After=network.target
[Service]
Type=simple
ExecStart=/home/用户名/frpc -u 你的用户ID -p 你的隧道ID
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
把 /home/用户名/ 换成 frpc 文件的实际绝对路径。用 pwd 看当前路径,用 ls -l 确认文件在不在。
After=network.target只表示网络管理栈启动了,不保证已经有可路由的地址。新版教程改成了After=network-online.target+Wants=network-online.target,开机抢跑的问题会少很多。- 如果 frpc 要用相对路径找配置或证书,在
[Service]里补一行WorkingDirectory=/home/用户名,比在ExecStart里写cd靠谱。
4.3 重载系统服务配置
sudo systemctl daemon-reload
4.4 设置开机自启并立即启动
sudo systemctl enable frpc.service
sudo systemctl start frpc.service
也可以合成一条:
sudo systemctl enable --now frpc.service
4.5 查看服务运行状态
sudo systemctl status frpc.service
正常状态应显示 Active: active (running)。
5. 服务管理与日志查看
| 操作 | 命令 |
|---|---|
| 查看服务状态 | sudo systemctl status frpc.service |
| 手动启动服务 | sudo systemctl start frpc.service |
| 手动停止服务 | sudo systemctl stop frpc.service |
| 手动重启服务 | sudo systemctl restart frpc.service |
| 查看实时日志(滚动) | sudo journalctl -u frpc.service -f |
| 查看最近 100 行日志 | sudo journalctl -u frpc.service -n 100 --no-pager |
| 查看全部日志(分页) | sudo journalctl -u frpc.service |
按 Ctrl+C 可退出 -f 模式的日志跟踪。
5.1 进程管理(非 Systemd 方式)
若使用 nohup 临时运行,可通过以下方式管理进程。
查找进程 ID:
ps aux | grep frpc | grep -v grep
输出第二列即为 PID。
终止进程:
kill PID
或按名称杀死:
pkill -f "frpc -u"
5.2 移除开机自启并删除服务
若不再需要开机自启,按顺序执行:
sudo systemctl stop frpc.service
sudo systemctl disable frpc.service
sudo rm /etc/systemd/system/frpc.service
sudo systemctl daemon-reload
6. 常见错误及解决方法
6.1 服务启动失败:status=203/EXEC
Active: activating (auto-restart) (Result: exit-code)code=exited, status=203/EXEC
可能原因:
ExecStart=路径错误或文件不存在。- 文件没有可执行权限。
ExecStart里写了 shell 语法(cd、&&、管道):systemd 不经过 shell,会把第一个词当成程序名。- 架构不对:ARM 机器装了 amd64 的包。
排查步骤:
第 1 步:确认文件存在且路径正确
ls -l /home/用户名/frpc
第 2 步:添加执行权限
chmod +x /home/用户名/frpc
第 3 步:直接运行,看具体报错
/home/用户名/frpc -u xxx -p xxx
第 4 步:检查依赖(大多数情况不需要)
ldd /home/用户名/frpc
frpc 是 Go 静态编译的单个二进制,正常输出是 not a dynamic executable,这行不是错误。
原文写「若显示 not found,安装 libfuse2」。这个结论不对:frpc 不依赖 FUSE,libfuse2 和它没有关系。真正常见的 203/EXEC 是路径错、没有执行权限、架构不匹配、ExecStart 里写了 shell 语法这四种。看到 Exec format error,直接换对应架构的包。
6.2 服务运行但日志显示 connection refused
frpc 已经成功连上远程服务器,但连不上内网的目标服务(如 192.168.110.42:8090)。
检查项:
- 内网服务是否已启动。
- 目标 IP 和端口是否正确。
- 若服务就在本机,建议目标地址改为
127.0.0.1:端口。
6.3 修改服务文件后不生效
执行重载和重启:
sudo systemctl daemon-reload
sudo systemctl restart frpc.service
6.4 忘记使用 sudo 打开服务文件导致无法保存
退出后重新用 sudo vim 或 sudo nano 打开。
附录:vim 编辑器常用操作(针对无 nano 环境)
| 操作 | 按键 / 命令 |
|---|---|
| 打开文件 | sudo vim 文件路径 |
| 进入插入模式(开始编辑) | 按 i |
| 退出插入模式 | 按 Esc |
| 保存并退出 | :wq |
| 不保存强制退出 | :q! |
| 删除当前行 | 按 dd |
| 撤销上一步 | 按 u |
| 查找关键词 | /关键词(按 n 下一个) |
| 替换整个文件内容 | :%s/旧/新/g |
安全提醒
- 命令行里的
-u和-p参数会被所有用户通过ps aux看到,建议改用配置文件frpc.ini存放认证信息,并把ExecStart改成ExecStart=/路径/frpc -c /路径/frpc.ini。 - 服务文件中的路径和参数应使用绝对路径,避免使用
~等相对符号。 - 定期检查日志文件大小,可配置日志轮转(logrotate)。
原文档到这里结束,它覆盖了从零开始部署 ChmlFrp 客户端的完整流程。若遇到未列出的问题,可用 journalctl -u frpc.service -n 50 查看详细日志。
新版教程在这份存档之上改了两件事:配置文件从 frpc.ini 变成 frpc.toml,守护方式多了 multi_runner 这一条路。回到 新版教程 对照着看即可。