frpc-client-win 教程：Windows 单文件 frpc 服务包装与部署

Windows 机器要接入内网穿透，最烦的是部署形态：frpc.exe 要配配置文件、配自启、配日志，换台机器又要重来一遍。frpc-client-win 把这件事收敛成一个文件：Go 编写的 Windows 后台服务包装程序，frpc.exe 通过 embed.FS 嵌进二进制，最终产物只有一个 EXE，注册为系统服务后开机自启，无需用户登录。本文从编译、安装、导入配置讲到日志排障，以及它怎么和 frps-manager 配合使用。

一、项目简介

frpc-client-win 是 AI-Agent 组织下的开源项目（MIT 协议），用 Go 编写。它的核心思路很简单：把 fatedier/frp 的 frpc.exe 嵌进自己的二进制里，再套一层 Windows Service 的壳。部署时只需要一个 EXE 文件，放到任意目录，执行 install 就注册成系统服务，start 之后开机自动运行，不需要用户登录，也不会弹出控制台窗口。

当前内嵌的是 frpc v0.70.1，最终产物约 18.9 MB（frpc.exe 16.7 MB + Go runtime 2.1 MB + 业务代码）。版本升级也很直接：去 GitHub 下载新版 frp 的 Windows 包，取出 frpc.exe 替换 assets/frpc.exe，重新编译即可。配置兼容两种格式：frpc.ini（旧版）和 frpc.toml（新版），优先使用 .ini。

二、功能特性

特性	说明
单文件部署	frpc.exe 通过 embed.FS 嵌入主程序，最终产物一个文件即可
Windows Service	注册为系统服务，开机自启，无需登录用户
配置兼容	同时支持 frpc.ini（旧版）和 frpc.toml（新版），优先 .ini
交互式导入	启动时若无配置文件，可在交互会话里用 import 命令拖入客户提供的 ini / toml
服务管理子命令	install / start / stop / remove + import + -d 控制台前台运行
完整日志	本服务日志写 logs/service.log，frpc 输出统一进 logs/service.log，便于集中取证
Windows 事件日志	同时写 Windows Event Log（source = frpc-client）

注意日志那一行：README 里写的是“frpc 输出统一进 logs/frpc.log（实际是 service.log）”，也就是说 frpc 子进程的输出和本服务的状态日志最终都混合写进 logs/service.log。查问题时只看这一个文件就够了，不用在两个日志之间来回翻。

三、架构与工作原理

程序的运行链路是标准的 Windows 服务模型：

Windows SCM（服务控制管理器）
  │ Start / Stop / Control
  ▼
Run() -> svc.Run("frpc-client", &handler{cfg})
  │
  ▼
handler.Execute() -> supervisor.Start() -> exec frpc.exe

代码分工也很清晰：main.go 是入口，根据子命令分派；internal/config 负责 frpc.exe / ini 路径与释放逻辑——服务启动时把内嵌的 frpc.exe 释放到磁盘再执行；internal/logger 是简易文件日志器；internal/service 实现 svc.Handler、frpc 子进程 supervisor，以及服务的安装、卸载、启停。supervisor 会看着 frpc 子进程，进程异常退出时按策略处理，服务本身由 SCM 托管。

配置检测的优先级是：EXE 同目录下的 frpc.ini 优先，如果没有 ini 再看 frpc.toml。两个都没有时，服务启动会失败，这时就用 import 子命令交互式导入一份配置。导入时按扩展名自动分发到 frpc.ini 或 frpc.toml。

四、适用场景

• 给客户交付内网穿透客户端：客户是 Windows 机器，不懂命令行，给他一个 EXE 加一份 frpc.ini，管理员远程执行两条命令就装好服务，后面全程不用客户动手；
• 办公室 Windows 服务器接入：跑在机房或办公室的 Windows Server 需要把 RDP、Web 管理后台、数据库端口映射出去，注册成服务后断电重启也能自己恢复；
• 临时演示与远程支持：工程师的 Windows 笔记本要临时暴露一个本地服务，用前台模式 -d 跑起来，用完 Ctrl+C 退出，不留服务残留；
• 批量部署：同一个 frpc.ini 模板分发到多台 Windows 机器，每台一个 EXE，配合 frps-manager 的多租户体系，按租户分配客户端和 token；
• 无值守设备：工控机、自助终端这类没人登录的 Windows 设备，服务形态是唯一可靠的运行方式。

五、编译构建

在任何装了 Go 的机器上都能交叉编译出 Windows 版本，不需要 Windows 环境：

GOOS=windows GOARCH=amd64 go build -ldflags "-s -w -H windowsgui" -o frpc-client.exe .

• GOOS=windows GOARCH=amd64：交叉编译目标是 64 位 Windows；
• -H windowsgui：编译为 GUI subsystem，服务运行时无控制台窗口，不会在桌面上闪黑框；
• -s -w：去除调试信息，减小体积；
• 当前内嵌 frpc v0.70.1，最终产物约 18.9 MB。

如果只想验证 Go 业务逻辑、不实际打包 frpc，可以用空文件占位 assets/frpc.exe，代码会正确处理缺失并报错，不会静默失败。升级内嵌的 frpc 版本分三步：先从 GitHub 的 fatedier/frp Releases 页面下载对应版本的 Windows 包（例如 frp_0.70.1_windows_amd64.zip），解压取出 frpc.exe 替换 assets/frpc.exe，再重新编译：

GOOS=windows GOARCH=amd64 go build -ldflags "-s -w -H windowsgui" -o frpc-client.exe .

升级时注意版本要和服务端的 frps 保持一致（当前是 0.70.1），跨大版本混用可能出现协议不兼容。README 里的验证状态说明：Windows vet 干净、Windows 编译通过（18.9 MB GUI EXE）、embed 验证通过（strings frpc-client.exe 能看到 fatedier/frp 字样）、Linux smoke 测试通过（config 包的 frpc 释放、ini 检测、优先级行为正确）。但 Windows 服务真实运行测试需要 Windows 环境或 wine，作者本机未做，建议你在 Windows 上跑一遍 install → start → 看 logs/service.log 和 Event Viewer。

六、安装与启动服务

以管理员身份打开 CMD（一定要管理员，否则注册服务会报权限错误），执行：

frpc-client.exe install
frpc-client.exe start

服务名是 frpc-client，显示名是 FRPC Client Service，启动类型为自动。安装后服务就注册进了 Windows SCM，以后每次开机自动启动，不需要用户登录。可以用系统自带的命令确认：

sc query frpc-client
sc qc frpc-client

服务启动时会检测 EXE 同目录下的配置文件：有 frpc.ini 就用它，没有就找 frpc.toml。所以部署顺序建议是：先把 frpc.ini 放到 EXE 同目录，再执行 install 和 start，一步到位。

七、导入配置文件

有两种方式把配置交给程序。第一种是直接放文件：把客户提供的 frpc.ini 放到 EXE 同目录，服务启动时自动检测。第二种是交互式导入，适合手头没有现成文件、需要现场接收配置的场景，在控制台运行：

frpc-client.exe import

按提示把配置文件拖入控制台窗口、回车即可。脚本会自动按扩展名分发到 frpc.ini 或 frpc.toml。导入完成后重启服务生效。

一份典型的 frpc.ini（从 frps-manager 的 Web 端下载的）长这样，放到 EXE 同目录就能用：

# Generated by frps-manager for client: office-pc
[common]
server_addr = your.frps.host
server_port = 7000
authentication_method = token
token = AbCdEf123456...    # 与所有 frpc 共用的 server token
admin_addr = 127.0.0.1
admin_port = 7400
admin_user = admin
admin_pwd = admin

[office-pc_rdp]
type = tcp
local_ip = 127.0.0.1
local_port = 3389
remote_port = 6002

[office-pc_web]
type = http
local_ip = 127.0.0.1
local_port = 8080
custom_domains = office.example.com

注意两点：第一，token 是共享密钥，不要通过聊天工具明文发给客户，最好用 frps-manager 的下载链接或加密渠道传递；第二，如果一台 Windows 机器上只跑这一个实例，admin_port 用默认的 7400 就行，多实例才需要逐个改掉。

八、控制台前台运行（调试用）

服务装好但连不上 frps 时，别急着改配置，先用前台模式跑起来看日志：

frpc-client.exe -d

也可以用 frpc-client.exe console，效果一样。日志同时输出到控制台和 logs/service.log，Ctrl+C 退出。前台模式能看到 frpc 子进程的完整输出，包括 login to server success、proxy added、start proxy success 这些关键行，确认没问题后再用服务模式跑。

九、停止与卸载服务

frpc-client.exe stop
frpc-client.exe remove

先 stop 再 remove，顺序不能反。卸载后服务从 SCM 里注销，但 EXE、配置文件和日志文件还留在原目录，需要手动删除。换配置的正确姿势是：stop 服务 → 替换 frpc.ini → start 服务；或者直接替换配置文件后重启服务，不需要重新 install。

十、日志与排障

服务运行后，目录结构是这样的：

frpc-client.exe        # 本程序（已嵌入 frpc.exe）
frpc.ini               # frpc 配置（优先）/ frpc.toml（备选）
logs/
  service.log          # 本服务日志 + frpc 输出（混合）

logs/service.log 会混合记录 frpc 子进程的所有输出和本服务的状态日志，是排障的第一手资料。同时程序还会写 Windows Event Log（source 是 frpc-client），在 Event Viewer（事件查看器）→ Windows 日志 → 应用程序里能看到，适合集中取证和审计。

现象	可能原因	排查方法
服务启动后立即停止	同目录下没有 frpc.ini / frpc.toml	看 logs/service.log；用 import 导入一份配置
install 报错权限不足	CMD 不是管理员身份	右键以管理员身份重新打开 CMD
token in login doesn't match	token 错误或已轮换	从 frps-manager 重新下载 frpc.ini
connection refused	frps 未启动或防火墙拦截	检查 frps 7000 端口是否可达；检查 Windows 防火墙出站规则
代理不生效	frpc.ini 里没有对应 proxy 段	确认下载的是最新 frpc.ini；前台 -d 模式看 proxy added 日志
服务状态是运行但仪表盘显示离线	frps dashboard 未同步	检查 frps 的 dashboard（:7500）是否可达

十一、与 frps-manager 配合使用

frpc-client-win 和 frps-manager 是一对：服务端用 frps-manager 的 Web 界面管租户、客户端和代理规则，Windows 客户端用 frpc-client-win 跑 frpc。标准流程是：

• 管理员在 frps-manager 里建租户、建用户、建 frpc 客户端、配代理规则；
• 在客户端页面点「frpc.ini」下载配置，发给 Windows 机器的操作者；
• Windows 机器上把 frpc-client.exe 和 frpc.ini 放到同一个目录；
• 管理员 CMD 执行 install 和 start；
• 回到 frps-manager 仪表盘，确认客户端在线、代理变绿；
• 以后改代理规则：在 Web 端改完重新下载 frpc.ini，替换 Windows 机器上的文件，重启服务（或直接用 frpc 的 reload 机制）。

这个组合的好处是 Windows 侧完全不用装 Go、不用装 frpc、不用写 systemd 单元，一个 EXE 加一份 ini 就完成部署，出了问题日志也只有一个文件可查。

十二、运维建议与已知限制

• 版本对齐：内嵌 frpc 的版本必须和服务端 frps 保持一致（当前 0.70.1），升级时两边一起升；
• 配置文件权限：frpc.ini 里有共享 token，文件不要放在公共目录，NTFS 权限只给管理员和 SYSTEM；
• 日志轮转：service.log 是追加写入的，长期运行会变大，定期归档或清理；
• 防火墙：Windows 防火墙一般不拦截出站连接，但如果装了第三方安全软件，需要放行 frpc-client.exe 的出站访问；
• 多实例：一台 Windows 机器跑多个客户端时，需要复制多份 EXE 到不同目录（服务名相同会有冲突，README 未说明多实例的服务名区分方式，部署前请先在一台机器上实测）；
• 已知限制：Windows 服务真实运行测试需要 Windows 环境或 wine，作者本机未做，上线前务必在目标 Windows 机器上完整跑一遍 install → start → 看 logs/service.log + Event Viewer。

总结一下：frpc-client-win 解决的是“Windows 机器怎么干净利落地跑 frpc”这个问题。一个 EXE、两个命令、一个日志文件，就是它的全部上手成本。配合 frps-manager 使用，服务端管规则、客户端只管跑，职责分得非常清楚。