📌 微服 x 群晖/飞牛 — hclient-cli 外网访问配置教程

⚠️观前提示 此文档适用场景为：
 **群晖/飞牛与微服不在同一局域网，需要通过外网简单访问.**
 
**若群晖/飞牛与微服同处相同局域网，则优先使用[netmap](https://appstore.lazycat.cloud/#/shop/detail/org.snyh.netmap)转发.**

------

# ✅ **步骤 1：下载 hclient-cli 并上传至群晖/飞牛**

从 Gitee 下载适合系统的版本：
 👉 https://gitee.com/lazycatcloud/hclient-cli

然后将文件上传到 NAS 目录。

📌 **示例文件：`hclient-cli-linux-amd64`**


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/2b4cd9c3-08b7-4331-ae7f-418579dea11f.png "image.png")

------

# ✅ **步骤 2：启用 SSH 并连接 NAS**

在群晖或飞牛中开启 SSH
 然后用终端工具（PuTTY / Terminal）连接 NAS。


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/43560f60-d19a-45e5-b986-a9a91fa28b66.png "image.png")

------

# ✅ **步骤 3：赋权 & 设置 capability**

进入上传目录后执行：

```bash
# 后续步骤需要用到root权限，切换到root身份
sudo -i

# cd到刚刚上传文件的目录,这里以飞牛为例
# 飞牛文件路径在/volX/1000/xxx路径/
# 群晖文件路径在/volumeX/xxx路径/
cd /vol1/1000/nvme/application/

# 添加执行权限
chmod +x ./hclient-cli-linux-amd64
```

> capability 允许非 root 用户创建 TUN 设备。
> 若需要设置可执行：
> `sudo setcap cap_net_admin=eip ./hclient-cli-linux-amd64`


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/d5582959-63be-4039-acbb-949d899e2a90.png "image.png")

------

# ✅ **步骤 4：启动 hclient（前台运行便于调试）**

```bash
./hclient-cli-linux-amd64 -tun
```

保持该终端开启，不要关闭。


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/1c5e8492-1fcd-4cc8-8d8c-83c70a68e839.png "image.png")

------

# ✅ **步骤 5：打开新终端执行微服认证**

### ① 添加盒子

```bash
curl -X POST 'http://127.0.0.1:7777/add_box?bname=$盒子名&uid=$用户名&password=$密码'
```

### ② 查看连接状态

```bash
curl 'http://127.0.0.1:7777/box_list'
```

（可插入“已添加但未 TFA 的状态截图”）

### ③ 输入 TFA 验证码

```bash
curl -X POST 'http://127.0.0.1:7777/add_tfa?bname=$盒子名&tfa=$验证码'
```

### ④ 再次确认状态

```bash
curl 'http://127.0.0.1:7777/box_list'
```

如果看到 **connected / online** 字样，则表示连接成功。


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/288a9a20-5ca6-4f66-944e-e62f46f4d60b.png "image.png")


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/5d76785f-c65f-40f4-ba9f-b884b3bc0112.png "image.png")



------

# ✅ **步骤 6：后台运行 hclient**

调试完成后 退出刚启动的前台hclient，用普通用户身份并添加 & 后台重新运行hclient，这次再运行就不会需要输入密码验证：

```bash
sudo ./hclient-cli-linux-amd64 -tun &
```

如需让其开机自动运行，也可写到 Task Scheduler 或启动脚本中。


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/6c7a62c2-ba6c-4597-8c88-356bd654a5fb.png "image.png")

------

# ✅ **步骤 7：在微服后台获取设备域名**

进入 **懒猫客户端 → 设备管理**
 找到你的 NAS 对应的 **设备域名**。


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/b58ba8ed-14aa-4762-b14f-9de25f1c87da.png "image.png")

------

# ✅ **步骤 8：通过域名访问群晖/飞牛 NAS**

在浏览器输入微服为你分配的域名，即可：

- 打开 DSM
- 下载文件
- 访问服务
- 使用反向代理端口访问内部应用


![image.png](https://dl.playground.lazycat.cloud/guidelines/625/db661066-bfd0-4338-ad4c-c9cf8cedee06.png "image.png")

------

# 🎉 **完成！现在 NAS 已可通过微服实现外网访问。**