ChmlFrp 部署文档
内网穿透 · 客户端部署

ChmlFrp 内网穿透部署文档

新版 0.70.1 的两条部署路线(多服务守护 / systemd 托管),加上旧版 0.50 教程的存档。面向零基础:照着复制、只改两行、能跑起来,出问题知道先看哪里。

  • 新版 ChmlFrp 0.70.1
  • 旧版 0.50 系列(存档)
  • 系统 Linux · systemd
  • 离线 单文件,无外部依赖

这份文档怎么用

三句话:

说明每段代码右上角都有「复制」

点一下就能整段复制,复制到的内容不含行号、不含语言标签。命令里的占位符(令牌、隧道 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:面板给的是一条启动命令(远程配置)

Shell
./frpc -u 你的用户令牌 -p 你的隧道ID

这种模式下配置由服务端下发,本地不需要配置文件。-p 可以写多个隧道 ID,用英文逗号分隔。

用法 B:面板给的是一整份配置文件

把它保存成 frpc.toml,然后显式指定:

Shell
./frpc -c frpc.toml

一份最小可用的 frpc.toml 长这样(字段名与 frp 0.70 一致,实际值以面板为准):

TOML
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.ini

frpc 的默认配置路径是 ./frpc.ini,而 0.70.1 的包里给的是 frpc.toml。所以必须写 -c frpc.toml,否则会直接报:

文本
open ./frpc.ini: no such file or directory

这不是配置写错了,是它根本没找到文件。

装好先验证配置

0.70.1 自带配置校验命令,改完配置先跑它,比「重启完才发现写错」快得多:

Shell
./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)
严格配置没有默认开启,字段拼错直接报错
包内文件只有 frpcfrpc + 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 引号写法、进程与信号、陷阱清单命令总起不来,或者要写复杂命令
提示先用新手版跑通,再回来看高手版

高手版里的每一条规则,新手版都已经替你写成了固定写法。跑通之后再读,会轻松很多。

说明示例按 0.70.1 写

本教程的命令用 -c frpc.toml。如果你用的是 0.50 旧版,把文件名换成 frpc.ini 即可,其余写法完全一样。

教程一 · 新手版(照着改就能跑)

这一版只解决四件事:放哪、怎么写、怎么启动、出问题看哪。语法原理一概不讲,需要时再翻高手版。

它到底替你干了什么

你只需要维护一个纯文本文件 services.conf,里面一行一条命令:

INI
/svr/frpc/frpc -c /svr/frpc/frpc.toml

剩下的它来做:

它做的事对你的意义
逐行启动命令,全部并行、互不阻塞不用给每个程序写一份 systemd 服务文件
崩溃(退出码非 0、被信号杀)后等 interval 秒再拉起半夜崩了也能自己回来
每条命令的输出单独写进 logs/,文件名是 序号_程序名.log出问题知道是哪一条在报错
停止时先发 TERM,等 5 秒再 KILL一般不会留下杀不掉的残留进程
首次运行自动生成 services.conf不用自己从零写格式
注意它不是 systemd 的替代品

它不管开机自启(要靠 systemd 守住它),也不做端口转发本身。它只是「命令的运行器」。

第一步:把目录和文件摆好

以 /svr/frpc 为例,换成你自己的目录也行,后面的路径跟着改:

文本
/svr/frpc/
├── frpc                ← 0.70.1 包里的可执行文件
├── frpc.toml           ← 0.70.1 包里的配置文件(把面板配置粘进去)
├── multi_runner.py     ← 守护脚本
├── services.conf       ← 第一次运行后自动生成
└── logs/               ← 第一次运行后自动生成

先把目录建出来:

Shell
sudo mkdir -p /svr/frpc

然后把 frpc、frpc.toml、multi_runner.py 放进去(WinSCP 拖拽或 scp 都行),再加执行权限:

Shell
sudo chmod +x /svr/frpc/frpc

chmod +x 只做一次。忘了这一步的典型现象是:命令明明没错,却一直重启,日志里写 Permission denied。

第二步:先跑一次,让它生成配置

services.conf 不用手写,脚本第一次运行会自己在同目录生成一份带注释的模板:

Shell
cd /svr/frpc
python3 multi_runner.py

它会打印这两行,然后退出:

文本
已创建配置文件: /svr/frpc/services.conf
请编辑该文件,写入要启动的命令,然后重新运行本脚本。

这是正常现象,不是报错。它此时还没有任何命令可执行。

注意这一步要在装 systemd 之前做

如果你已经配好了 multi_runner.service 再去启动,它会「生成配置 → 退出 → 被 systemd 拉起 → 再退出」,日志每 10 秒刷一次。先按下面的步骤把配置写好,再交给 systemd。

第三步:先把命令手动跑通

不要一上来就交给守护脚本。 先在终端把要托管的命令原样跑一遍:

Shell
cd /svr/frpc
./frpc -c frpc.toml

看到 login to server success 之类的日志,说明配置和网络都没问题,按 Ctrl+C 停掉。

这一步的意义:命令本身有问题(配置错、令牌错、网络不通)时,守护脚本只会「重启—失败—再重启」,日志刷得飞快,反而看不出原因。手动跑一次,报错直接打在屏幕上。

第四步:编辑 services.conf

Shell
sudo nano /svr/frpc/services.conf

文件里已经有三行全局配置和一堆注释,把最后的示例行改成你的命令即可:

INI
interval=10
restart_on_success=0
log_dir=logs

# 下面这行换成你的命令
/svr/frpc/frpc -c /svr/frpc/frpc.toml

保存:nano 里按 Ctrl+O 再回车,然后 Ctrl+X 退出。

规则只有四条:

  1. 一行一条命令,行首行尾的空格会被忽略。
  2. 空行和 # 开头的行不执行,可以拿来写注释。
  3. 命令行里不要写行内 # 注释,# 后面的字会被当成参数传给程序。
  4. 想给某一条单独设置重启间隔,在那一行末尾加 @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,看日志

Shell
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 窗口看日志:

Shell
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 守住(强烈建议)

Shell
sudo nano /etc/systemd/system/multi_runner.service
INI
[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

三个地方按实际改:

然后让它生效并开机自启:

Shell
sudo systemctl daemon-reload
sudo systemctl enable --now multi_runner
sudo systemctl status multi_runner --no-pager

看到 Active: active (running) 就成了。

改完怎么生效

你改了什么执行什么影响
services.confsudo systemctl restart multi_runner所有命令重启一次,会短暂断线
frpc.tomlsudo systemctl restart multi_runner同上
multi_runner.pysudo systemctl restart multi_runner同上
multi_runner.servicesudo 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.tomlcd 被当成程序名,找不到,无限重启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 '...' 里又套单引号引号提前结束,命令被拆乱内层改用双引号

最后一条的典型例子,这样写很难读也容易错:

INI
bash -c 'cd /svr/frpc && exec ./frpc -c '"'"'frpc.toml'"'"''

直接写成:

INI
bash -c 'cd /svr/frpc && exec ./frpc -c "frpc.toml"'

出问题了,按这个顺序查

  1. 服务在不在跑:sudo systemctl status multi_runner --no-pager,看 Active: 是不是 active (running)。
  2. 脚本自己有没有报错:sudo journalctl -u multi_runner -n 50 --no-pager。
  3. 业务日志:ls -l /svr/frpc/logs/,再 tail -n 50 对应文件。
  4. 把命令复制出来手动跑:报错直接显示,比看循环重启的日志快得多。

日志里出现这些词,对应的通常是:

日志里的词说明怎么办
命令解析失败引号没闭合,这一行被整行跳过检查单引号、双引号是否成对
中没有可执行的命令services.conf 里只有注释,没有命令按第四步加一行命令,再 restart
无法打开日志文件log_dir 指向的目录不可写改回 log_dir=logs,或给目录写权限
Permission denied没有执行权限chmod +x
No such file or directory路径写错,或工作目录不对全部改成绝对路径
connection refused本机服务没起来,或端口写错先手动访问内网地址确认
每隔几秒重启一次命令本身在秒退手动跑,看它退出前的报错
提示求助时贴什么

「systemctl status 的最后 20 行」+「logs/ 里对应文件的最后 50 行」,基本就能定位。只发一句「起不来」,谁也猜不到。

到这里就够了

记住三句话:

下面高手版把这三句话背后的规则全部讲清楚。

教程一 · 高手版(深度解析 Shell 语法与脚本行为)

下面这一份讲的是脚本内部怎么解析、什么会坏、为什么坏。不影响你把服务跑起来;日常排错时按目录跳到对应小节即可。

说明读法

先看第一节的「解析链路总览」,建立「配置文件 → 分词 → exec」这三层的印象;再按需要查后面的规则。第六、第八节是排错时翻得最多的。

一、解析链路总览

一条配置行从文件到真正执行,要经过三层处理,任何一层出错都会导致"命令看起来对、就是起不来":

文本
配置文件一行
   │
   ├─ 第 1 层:行级规则(本脚本)      去空白 / 跳空行 / 跳 # 注释行 / 剥离尾部 @N / 识别全局配置行
   │
   ├─ 第 2 层:shlex 分词(本脚本)    按 POSIX 规则切分成参数列表;不是 shell,不展开任何东西
   │
   └─ 第 3 层:内核 exec(Popen)      直接执行列表第 1 项;只有显式写 bash -c 时才进入真正的 shell 语义

关键结论:本脚本默认不经过 shell。第 2 层只是"把字符串切成参数数组",它不做变量展开、不做通配符展开、不解释 && | ; > () cd ~ $。所有 shell 语法都必须通过 bash -c '...' 显式引入。


二、第 1 层:行级规则

2.1 空行与注释
文本
# 这是注释,正确
./frpc -c frpc.ini        # 这不是注释,# 和"这不是注释"会成为参数

需要行内注释时用 bash -c:

INI
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*$:行尾"空白 + @ + 数字"会被剥离,作为该命令独立的重启间隔。

INI
./frpc -c frpc.ini @10          # 间隔 10s,命令是 ./frpc -c frpc.ini
bash -c 'cd /x && exec ./y' @5  # 间隔 5s,引号内的内容不受影响

会误伤的情况:命令本身以"空格 + @数字"结尾,例如参数是 @123:

INI
./app --token @123        # 被误判:命令变成 ./app --token,间隔 123 秒

规避:包进 bash -c,因为整行结尾是引号,正则不匹配:

INI
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 单引号

内部一切字面,包括 $ \ " ` && | > # @ 空格。不能包含单引号本身(要包含就结束单引号、写 \'、再开单引号,见第五节)。

INI
bash -c 'echo $HOME && ls *.log'   # 整段是一个参数交给 bash
3.4 双引号

内部保留空白和大多数特殊字符,但反斜杠仍部分生效:\" → ",\\ → \,其余 \x 按字面保留 \x。不做变量展开(shlex 不是 shell)。

INI
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 '...' 包裹,否则会失败或行为不符预期:

而下面这些不需要 shell,直接写即可(脚本原生支持):


五、bash -c 的引号工程

5.1 基本形式
INI
bash -c '<shell 脚本内容>'

经过 shlex 后变成 ["bash", "-c", "<shell 脚本内容>"],再由 bash 自己解析第三段。这就是"把 shell 请回来"的唯一入口。

5.2 外层单引号(首选)

外层单引号最稳,因为 shlex 对它内部完全不做处理,内容原样传给 bash。

问题:shell 脚本内容里若需要单引号,单引号不能嵌套。解决办法是经典的 '\'' 四字符拼接——结束单引号、转义出一个单引号、再开单引号:

INI
bash -c 'cd /volume1/frp && exec ./frpc -c '"'"'frpc.ini'"'"''

这种拼法很难看,所以外层单引号 + 内层用双引号是常规做法:

INI
bash -c 'cd /volume1/frp && exec ./frpc -c "frpc.ini"'
bash -c 'cd /volume1/frp && exec ./frpc -c "my config.ini"'
5.3 外层双引号

当内容里需要大量单引号、且不含 $ ` " \ 时可用:

INI
bash -c "cd /volume1/frp && exec ./frpc -c 'frpc.ini'"

注意 shlex 对双引号内反斜杠的处理,避免在双引号层写 \"、\\。

5.4 exec 的作用
INI
bash -c 'cd /x && exec ./y'      # 推荐
bash -c 'cd /x && ./y'           # 可行,但不推荐

exec 只能用于"shell 脚本的最后一条命令",且不能用在管道左端或需要后续语句的位置(exec 会替换掉 shell,后面的语句不执行)。

5.5 多层嵌套

bash -c 里再套 bash -c 时,每层各用一套引号,从外到内交替:

INI
bash -c 'bash -c "echo inner"'

一般不需要两层;出现两层说明可以用一层 + ; 或 && 简化。


六、Shell 语法逐项详解(对照本程序行为)

以下每条都给出"错误写法 → 实际发生什么 → 正确写法"。

6.1 命令序列 ;
INI
chmod +x /svr/frpc/frpc ; /svr/frpc/frpc -c /etc/frpc.ini

错误:shlex 后 ; 是参数,chmod 会去改一个叫 ; 的文件,失败,脚本按间隔无限重试这个失败的 chmod。

正确:

INI
bash -c 'chmod +x /svr/frpc/frpc; exec /svr/frpc/frpc -c /etc/frpc.ini'
6.2 逻辑与 && / 逻辑或 ||
INI
cd /volume1/frp && ./frpc -c frpc.ini

错误:&& 被当参数,cd 是 shell 内置、系统中通常没有 /usr/bin/cd,Popen 直接 FileNotFoundError(或找到 /bin/cd 的极少数系统上行为古怪)。

正确:

INI
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'

&& 语义:前一条成功(退出码 0)才执行后一条。需要"无论前一条成败都执行"用 ;;需要"前一条失败才执行"用 ||。

6.3 子 shell ( ... ) 与分组 { ...; }

一种常见写法:

INI
(cd /volume1/frp && ./frpc -c frpc.ini)

错误:shlex 得到 ["(cd", "/volume1/frp", "&&", "./frpc", "-c", "frpc.ini)"],第 1 项 (cd 不是可执行文件,FileNotFoundError,无限重试。

正确:

INI
bash -c '(cd /volume1/frp && exec ./frpc -c frpc.ini)'

但这里的 ( ) 没有必要,因为 bash -c 本身已经是独立 shell,cd 只影响这个 bash,不会污染本脚本或其他服务。bash -c 已经是天然的"子 shell 隔离"。只有在同一个 bash -c 脚本里需要"一段 cd 不影响后续语句"时才需要 ( ):

INI
bash -c '(cd /a && exec ./one) & (cd /b && exec ./two) & wait'

{ ...; } 是分组,不创建子 shell,cd 会影响后续;注意 { 后要有空格、} 前要有 ;。

6.4 管道 |
INI
./frpc -c frpc.ini | grep -v health

错误:| 是参数,frpc 收到额外三个参数,可能报错或被忽略。

正确:

INI
bash -c 'exec ./frpc -c frpc.ini 2>&1 | grep --line-buffered -v health'

注意两点:

  1. 管道左端不能写 exec。exec 会替换掉 bash 自己,右边 grep 就没人启动了。整条 bash -c 的退出码是管道最后一环(grep)的退出码——frpc 崩溃时 grep 仍可能返回 0,重启判定会失效。要守护崩溃,别在管道末端判活;或者用 set -o pipefail; 让管道任一环失败即整体失败:
    INI
    bash -c 'set -o pipefail; ./frpc -c frpc.ini 2>&1 | grep --line-buffered -v health'
  2. grep 默认块缓冲,日志会延迟。加 --line-buffered。
6.5 重定向

本脚本已经把子进程的 stdout 接到日志文件、stderr 合并进 stdout(stderr=subprocess.STDOUT)。命令里再写重定向会覆盖这个行为:

INI
./frpc -c frpc.ini > /var/log/frpc.log 2>&1

错误:> 2>&1 是参数。正确:

INI
bash -c 'exec ./frpc -c frpc.ini > /var/log/frpc.log 2>&1'

但这样日志就不写进本脚本的 logs/ 目录了,脚本的日志文件只剩空壳。通常没必要——直接用脚本的日志即可。唯一值得用的是丢弃输出:

INI
bash -c 'exec ./noisy-app --quiet 2>/dev/null >/dev/null'

或只丢弃 stderr:

INI
bash -c 'exec ./app 2>/dev/null'

注意 stdin 已被脚本接到 /dev/null,命令里的 < 重定向仍可覆盖它,但交互式命令整体不适合本脚本(见第八节)。

6.6 工作目录 cd

脚本没有暴露 cwd 配置,Popen 的 cwd 是运行脚本时的当前目录,不是配置文件所在目录,也不是命令里可执行文件所在目录。因此:

正确:

INI
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'

或干脆用绝对路径,无需 shell:

INI
/volume1/frp/frpc -c /volume1/frp/frpc.ini

能用绝对路径就不用 cd,少一层 shell、少一类引号问题。

6.7 变量赋值与展开
INI
FOO=bar ./app

错误:shlex 得到 ["FOO=bar", "./app"],Popen 找名为 FOO=bar 的可执行文件,FileNotFoundError,且脚本会无限重试。这是最隐蔽的陷阱之一,因为命令行里这样写是完全合法的 shell 语法。

正确,两种:

INI
env FOO=bar ./app                                  # 用 env 命令,不需要 shell
bash -c 'export FOO=bar; exec ./app'               # 需要 shell 时

引用变量:

INI
bash -c 'exec ./app --home "$HOME" --conf "${CONF_DIR:-/etc/app}"'

注意外层单引号让 $HOME 原样到达 bash,由 bash 展开。若外层用双引号,shlex 虽不展开 $,但会处理反斜杠,容易出岔子——坚持单引号。

需要把脚本环境传入:

INI
bash -c 'exec ./app --token "$FRPC_TOKEN"'

前提是运行 multi_runner.py 的那个 shell 里 export 了 FRPC_TOKEN,子进程继承环境。

6.8 命令替换 $(...)
INI
bash -c 'exec ./app --start-time "$(date +%s)"'

`...` 等价但可读性差、易与引号冲突,优先 $()。

6.9 通配符
INI
./app --conf /etc/app/*.conf

错误:* 原样传给程序。正确:

INI
bash -c 'exec ./app --conf /etc/app/*.conf'

风险:匹配到多个文件时,程序会收到多个参数。需要精确时用 find/ls 在 shell 里处理,或直接写全路径。

6.10 波浪号 ~
INI
./app --home ~/data

错误:~ 原样传入(Popen 不做展开,程序多半也不做)。正确:

INI
bash -c 'exec ./app --home "$HOME/data"'
6.11 后台 & —— 禁止
INI
./app &

错误且危险:& 是参数,shlex 后 Popen 执行 ./app 并把 & 当参数,./app 立即以前台方式运行——这时还能"碰巧"工作。但如果写的是 bash -c './app &':

守护程序里永远不要写 &。脚本本身已经负责"启动、等待、重启",命令必须是前台常驻进程。

6.12 nohup / setsid / disown —— 禁止

同理,这些工具的目的是"脱离父进程独立存活",与本脚本"由我守护、由我停止"的模型冲突。脚本已用 start_new_session=True 处理进程组隔离,不需要 setsid。

6.13 source / .
INI
bash -c '. /etc/profile; . /opt/app/env.sh; exec ./app'

用于加载环境脚本后再启动。

6.14 ulimit / umask
INI
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() 的返回码:

所以 bash -c 的退出码必须是"你关心的那个进程"的退出码。加 exec 时天然满足;不加 exec 时是 bash 脚本最后一条命令的退出码;用管道时默认是最后一环的退出码(用 pipefail 修正)。

7.2 进程组与停止

start_new_session=True 让每个服务成为新会话的首进程,之后 killpg(os.getpgid(pid), SIGTERM) 发给整组:

脚本停止流程:SIGTERM → 等 5 秒 → SIGKILL。

7.3 子进程清理

目标进程自己 fork 的子进程若不在同一进程组(比如自己又 setsid 了),脚本杀不到。避免在被守护的命令里再 setsid / daemonize。


八、陷阱清单

按踩坑概率排序:

  1. && ; | 直接写在配置里:被当参数,命令失败,无限重启。→ bash -c。
  2. VAR=x cmd 直接写:Popen 找名为 VAR=x 的文件,失败,无限重启。→ env 或 bash -c。
  3. cd 直接写:内置命令无对应可执行文件,失败,无限重启。→ bash -c 'cd ... && exec ...'。
  4. 行内 #:不是注释,成为参数。→ 删掉,或 bash -c。
  5. 尾部 @N 误伤:命令末尾"空格 + @数字"被当间隔。→ 包进 bash -c。
  6. 单引号未闭合:整行被跳过(看日志有无"命令解析失败"),不会重启。
  7. 单引号嵌套单引号:外层单引号提前结束,后半段被 shlex 重新分词,行为错乱。→ 内层用双引号。
  8. bash -c './app &':服务被判定立即正常结束,进程变孤儿。→ 去掉 &。
  9. bash -c 'exec ./a | ./b':exec 在管道左端无意义且破坏右侧启动。→ 左端不写 exec,加 pipefail。
  10. 命令里重定向到自己的日志:脚本的 logs/xx.log 变空壳,两套日志并存。→ 通常不需要重定向。
  11. 交互式命令(需要 stdin、需要 tty):stdin 已接 /dev/null,必然失败或挂起。本脚本不适合跑交互程序。
  12. 用相对路径配置:工作目录是"运行脚本时的目录",不是配置文件目录。→ 绝对路径或 cd。
  13. ./frpc 但没 chmod +x:PermissionError,无限重启。→ 启动前手动 chmod +x 一次。
  14. 密码/令牌含 shell 特殊字符($ ! ` \ "):在双引号层会被处理。→ 用单引号层,或在单引号内用双引号包参数。
  15. pipefail 缺失:管道左侧崩溃被右侧掩盖,永不重启。→ set -o pipefail。

九、场景配方

全部为可直接粘贴进 services.conf 的写法。

1. 最简单:绝对路径常驻进程

INI
/svr/frpc/frpc -u 7ylySJuVtDt5rRCEv3ESIeD2 -p 339931

2. 需要特定工作目录、配置文件是相对路径

INI
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini'

3. 先 chmod 再启动(不推荐,推荐事先手动 chmod)

INI
bash -c 'chmod +x /svr/frpc/frpc && exec /svr/frpc/frpc -u USER -p PORT'

4. 设置环境变量

INI
bash -c 'export FRPC_LOG_LEVEL=info; export TZ=Asia/Shanghai; exec ./frpc -c frpc.ini'

或不需要 shell 时:

INI
env TZ=Asia/Shanghai /svr/frpc/frpc -c /etc/frpc.ini

5. 提高文件描述符上限

INI
bash -c 'ulimit -n 65535; exec /opt/app/server --port 9000'

6. 过滤日志后再交给脚本记录

INI
bash -c 'set -o pipefail; exec 2>&1 | grep --line-buffered -v -E "health|ping"'

注意:这种写法里没有 exec 目标进程,见 6.4 的退出码问题。更稳的写法是让程序自己降噪,而不是在 shell 里过滤。

7. 丢弃全部输出

INI
bash -c 'exec /opt/app/worker --quiet >/dev/null 2>&1'

8. 启动前等待依赖端口就绪

INI
bash -c 'until nc -z 127.0.0.1 3306; do sleep 1; done; exec /opt/app/api --port 8080'

9. 单实例保护(防止上次残留进程)

INI
bash -c 'exec flock -n /var/lock/frpc.lock /svr/frpc/frpc -c /etc/frpc.ini'

flock 拿不到锁立即失败退出(非 0),脚本会重启,直到锁释放——正好实现"等旧实例退出再拉起"。

10. 多命令顺序依赖,最后一条常驻

INI
bash -c 'mkdir -p /var/run/app && chown app:app /var/run/app && exec runuser -u app -- /opt/app/server'

11. 参数含空格与特殊字符

INI
bash -c 'exec /opt/app/server --name "my server" --token "a$b!c"'

外层单引号保证 $ ! 原样到达 bash,内层双引号保证空格不被拆开;bash 展开时双引号内 $b 仍会尝试展开——若令牌里真有 $,改用单引号内层:

INI
bash -c 'exec /opt/app/server --name "my server" --token '\''a$b!c'\'''

这种多层引号极难维护,更简单的办法是把敏感参数放进环境变量或用配置文件:

INI
bash -c 'exec /opt/app/server --name "my server" --token "$APP_TOKEN"'

12. 带独立重启间隔

INI
bash -c 'cd /volume1/frp && exec ./frpc -c frpc.ini' @10

13. 定时型"常驻"(程序秒退,需要它反复跑)

INI
interval=60
restart_on_success=1
INI
/opt/scripts/collect.sh

配合 restart_on_success=1,正常退出也会每 60 秒重跑,等价于简易定时器。

14. 需要以其他用户运行

INI
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 发行版都有)。确认一下:

Shell
systemctl --version

能打印出版本号就行。如果提示 command not found,说明这套系统(或这个容器)没有 systemd,只能用教程一的 multi_runner。

版本内容适合
新手版一份能直接用的 frpc.service,标出只需要改的两行,附一键部署脚本第一次写 systemd 服务
高手版Type=、Restart=、依赖排序、环境变量、模板单元、安全加固要排查「为什么不重启 / 为什么不自启」
提示为什么不用 nohup

nohup ./frpc ... & 只能让程序在 SSH 断开后活着,机器重启就没了,进程崩了也不会自己回来。它适合临时测试,不适合长期放着。长期跑就用本文的 systemd 方式。

教程二 · 新手版(只教怎么写、怎么改)

下面这份模板来自教程原文,路径以 NAS 上的 /volume1/frp/frp3 为例,换成你自己的目录即可。

说明0.70.1 的配置文件叫 frpc.toml

原文示例里写的是 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 守护服务:

INI
[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

全文只需要你改 两行,其他原样保留:

如果配置文件叫 frpc.toml 而不是 frpc.ini,只改 -c 后面那个文件名即可。

每个字段是干什么的(只说你用得上的)

[Unit] 段

[Service] 段

[Install] 段

有需求时怎么改

需求:frpc 崩溃后马上重启,不要等。

→ 把 RestartSec=15s 改成 RestartSec=3s 或 5s。

需求:只在异常退出时重启,正常退出就不管。

→ 把 Restart=always 改成 Restart=on-failure。这样 exit 0 不会触发重启,只有非零退出或被信号杀掉才重启。

需求:以非 root 用户运行 frpc。

→ 在 [Service] 段加两行:

INI
User=frp
Group=frp

前提是该用户对 WorkingDirectory 和配置文件有读权限,对 frpc 二进制有执行权限。

需求:清理某个环境变量(比如之前遇到的 GODEBUG)。

→ 在 [Service] 段加:

INI
UnsetEnvironment=GODEBUG

如果 systemd 版本不支持,改成 Environment="GODEBUG=" 也能达到置空的效果。

需求:限制 frpc 的内存占用。

→ 加 MemoryMax=256M(超出立即 OOM 杀掉本服务)或 MemoryHigh=200M(软限制,超过后尽量回收)。systemd 通过 cgroup 做限制,比 ulimit 更可靠。

改完之后必须做什么

只改配置不重启:systemctl restart frpc。

改了 service 文件本身:必须先 systemctl daemon-reload,否则修改被忽略。然后 systemctl restart frpc。

标准安全顺序:

Shell
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 终端:

Shell
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 不会重新读文件。原文已经写了,这里再强调一次——「改了没生效」九成是漏了它。

提示0.70.1 可以先验证配置再重启
Shell
/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 第一个参数作为可执行文件。所以:

这不是 systemd“不支持 Shell”,而是它有意避免 Shell 带来的不确定性和额外进程层级。工作目录、环境、用户、权限、资源限制,全部由 systemd 在 execve 之前或通过 cgroup 施加。

2.2 [Unit] 段:依赖与排序语义

After= 和 Before= 是排序约束,只规定“谁先谁后”,不保证对方一定被启动。
Wants= 和 Requires= 是依赖约束:Wants 是弱依赖,对方启动失败不影响本服务继续启动;Requires 是强依赖,对方失败本服务也失败。

对于 frpc 这种网络客户端,推荐组合是:

INI
After=network-online.target
Wants=network-online.target

network.target 在启动阶段的语义很弱:它只表示网络管理栈已启动,此时接口是否已配置、是否已有可路由地址并不确定;它真正可靠的语义在关机阶段(保证在关机时先停掉依赖网络的服务)。network-online.target 才是“网络已经可用”的同步点,它会主动等待网络管理软件报告“上线”。对于“开机后必须立即连上服务端”的 frpc,后者更合适。

但官方文档也提醒:不要滥用 network-online.target。它主要面向没有网络就无法工作的客户端软件;服务端软件通常不需要等网络完全 online 才能接受本地连接。frpc 属于典型客户端,所以用它是合理的。

2.3 [Service] 段:进程模型与生命周期

Type= 决定 systemd 怎么判断“启动完成了”。

Restart= 的精确语义:

Restart=always 有一个容易被忽略的细节:systemd 默认有启动频率限制。如果在短时间内反复崩溃,达到 StartLimitBurst(默认 5 次 / StartLimitIntervalSec 默认 10 秒)后,systemd 会放弃重启并标记为 failed。如果你确实希望“无论如何都一直拉起”,需要在 [Unit] 段显式放宽限制:

INI
StartLimitIntervalSec=0

设为 0 表示禁用启动频率限制。否则一个持续秒退的 frpc 可能在几次重启后被 systemd 彻底放弃。

RestartSec= 只控制两次重启之间的睡眠时间,与 Restart= 配合使用。设得太短(如 0)会让崩溃循环迅速触发频率限制;设成 15s 可以在“及时恢复”和“给系统喘息”之间取得平衡。

WorkingDirectory= 在 execve 之前通过 chdir() 设置进程 cwd。它影响 frpc 内部所有相对路径的解析。即使 ExecStart 和 -c 都用了绝对路径,某些 frpc 内部逻辑(如证书、日志、临时文件)仍可能依赖 cwd,所以这个字段不是“可选的装饰”,而是确定进程行为的一部分。

ExecStart= 的前缀语义(高手会用到但新手通常不需要):

这些前缀是 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 的环境:

Shell
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 完全解耦:

systemctl enable --now 是两者的原子组合,适合一键部署。

2.6 验证、调试与依赖分析

静态验证 unit 语法:

Shell
systemd-analyze verify /etc/systemd/system/frpc.service

它会在不启动服务的情况下检查指令是否合法、可执行文件是否存在、依赖是否有明显问题。

查看启动链和耗时:

Shell
systemd-analyze critical-chain frpc.service

它会显示从 default.target 到 frpc.service 的完整依赖路径,以及每一步是否成功、耗时多少。如果 frpc 启动被 network-online.target 拖慢,这里会直接暴露出来。

查看依赖图:

Shell
systemd-analyze plot > deps.svg

生成全系统启动时序图(需要 graphviz),适合排查“为什么 frpc 在某个服务之前/之后启动”。

日志的权威来源:systemctl status 只显示最近几行且会被省略。完整原因永远在:

Shell
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 文件。用模板单元:

文件名:[email protected]

INI
[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 是实例名。启动:

Shell
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] 段可以逐步收紧:

INI
User=frp
Group=frp
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/volume1/frp/frp3

这些指令不会改变 frpc 的业务逻辑,但会限制它“万一被攻破能做什么”。生产环境建议在功能验证通过后逐项加入,用 systemd-analyze security frpc.service 查看当前 unit 的安全评分和剩余暴露面。

2.9 编辑与重载的精确规则

安全的编辑命令:

Shell
systemctl edit --full frpc

它会用 $EDITOR 打开完整 unit 文件,保存后自动触发 daemon-reload(取决于 systemd 版本),比手动 cat > 再 daemon-reload 少一步遗漏风险。

2.10 一键部署脚本的工程化写法

新手版给的是“改两行就粘贴”的版本。高手版的一键脚本应该具备幂等、前置校验、失败早退:

Shell
#!/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)。原文保留,只做了三类修正:

项目旧版(本部分)新版(第一部分)
配置文件frpc.ini(INI)frpc.toml(TOML)
启动参数-u 用户ID -p 隧道ID-u 用户令牌 -p 隧道ID
守护方式nohup 或 systemdmulti_runner 或 systemd
注意新装的机器不要照这份做

两版的操作思路(上传、解压、赋权、systemd 托管)是一样的,但配置文件格式和参数含义不同。新机器请直接看第一部分;本部分留着,是给旧机器、旧配置对照用的。

1. 环境与前置条件

说明整理注:先确认架构再下载

先执行 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 命令提示符)

Shell
scp -P 22 C:\本地路径\ChmlFrp-0.51.2_251023_linux_arm.tar.gz 用户名@NAS_IP:/home/用户名/

方式三:SMB 共享

在 Windows 运行 \\NAS_IP,复制粘贴到共享文件夹,再通过 SSH 移动到目标目录。

2.2 解压压缩包

Shell
tar -xzvf ChmlFrp-0.51.2_251023_linux_arm.tar.gz

解压后会得到一个与压缩包同名的目录,先进入目录再操作:

Shell
cd ChmlFrp-0.51.2_251023_linux_arm

目录里包含 frpc(主程序)、frpc.ini(配置文件模板)等。

2.3 添加执行权限

Shell
chmod +x frpc

3. 临时后台运行(使用 nohup)

此方式使程序在 SSH 断开后继续运行,但重启后不会自动启动,适合短期测试。

Shell
nohup ./frpc -u 你的用户ID -p 你的隧道ID > frpc.log 2>&1 &

查看实时日志:

Shell
tail -f frpc.log

按 Ctrl+C 退出日志查看。

说明整理注:0.70.1 的参数含义变了

0.70.1 里 -u 传的是用户令牌、-p 传的是隧道 ID 列表,和这里写的「用户 ID」不是一回事。旧版参数以旧版面板为准,新版请看第一部分。

4. 配置为 Systemd 服务(开机自启 + 崩溃自动重启)

将程序托管给系统服务管理器,实现开机自启和异常退出后自动重启。

4.1 创建服务文件

服务文件位于 /etc/systemd/system/frpc.service,需使用 sudo 权限创建。

方式 A:nano 编辑器(若已安装)

Shell
sudo nano /etc/systemd/system/frpc.service

输入内容后按 Ctrl+O 保存,Ctrl+X 退出。

方式 B:vim 编辑器(系统自带)

Shell
sudo vim /etc/systemd/system/frpc.service

按 i 进入插入模式,输入内容。完成后按 Esc,输入 :wq 保存退出。

4.2 服务文件内容

INI
[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 重载系统服务配置

Shell
sudo systemctl daemon-reload

4.4 设置开机自启并立即启动

Shell
sudo systemctl enable frpc.service
sudo systemctl start frpc.service

也可以合成一条:

Shell
sudo systemctl enable --now frpc.service

4.5 查看服务运行状态

Shell
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:

Shell
ps aux | grep frpc | grep -v grep

输出第二列即为 PID。

终止进程:

Shell
kill PID

或按名称杀死:

Shell
pkill -f "frpc -u"

5.2 移除开机自启并删除服务

若不再需要开机自启,按顺序执行:

Shell
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

可能原因:

排查步骤:

第 1 步:确认文件存在且路径正确

Shell
ls -l /home/用户名/frpc

第 2 步:添加执行权限

Shell
chmod +x /home/用户名/frpc

第 3 步:直接运行,看具体报错

Shell
/home/用户名/frpc -u xxx -p xxx

第 4 步:检查依赖(大多数情况不需要)

Shell
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)。

检查项:

6.3 修改服务文件后不生效

执行重载和重启:

Shell
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 这一条路。回到 新版教程 对照着看即可。