LinkLoom 研发网客户端 — 部署与使用文档

本文档基于 研发网登录教程.pdf 及目录内现有脚本（deploy.sh / register_service.sh / start_jar.sh / 启动.bat / config.yml）整理，覆盖 Windows / Linux / macOS 三种平台的部署、配置、启动与运维。

一、产品简介

LinkLoom 是一个用于接入"研发网"（虚拟组网）的客户端工具，核心能力：

  • 通过 TUN 虚拟网卡接入研发网，获取虚拟 IP，与同网络下的其他设备互通。
  • 内置 端口转发 模块，可把虚拟网络、本机或局域网中的服务暴露给其他设备。
  • 跨平台支持：Windows、Linux、macOS。
  • 服务化运行：Linux 下注册为 systemd 服务，macOS 下注册为 launchd 服务，开机自启动、崩溃自动拉起。

目录结构（交付包）

tesgt/
├── app-1.1.1.jar              # LinkLoom 主程序（Spring Boot 可执行 JAR）
├── app-1.1.1.jar.bak          # 旧版本备份
├── config.yml                 # 主程序配置文件（用户必须修改）
├── LinkLoom.exe               # Windows GUI 启动器
├── 启动.bat                   # Windows 一键启动脚本
├── deploy.sh                  # Linux 部署脚本（含 JRE 自动安装）
├── register_service.sh        # Linux systemd 服务精简注册脚本
├── start_jar.sh               # macOS / 通用启动脚本
├── com.user.yourapp.plist     # macOS launchd 服务模板
├── logs/                      # 运行日志目录
├── 研发网登录教程.pdf          # 官方使用教程
└── 端口转发/                  # 独立端口转发服务（可选）
    ├── portforward.jar
    ├── port-forward.yml
    ├── start.bat
    ├── start.sh
    └── logback.xml

二、前置准备

项目要求
操作系统Windows 10+ / 主流 Linux（含 systemd）/ macOS
JavaJRE / JDK 17 或以上（脚本可自动下载，也可手动安装）
网络权限安装 TUN 虚拟网卡需 管理员 / root 权限
浏览器用于登录研发网控制台创建 apiKey
研发网账号需联系管理员开通（参见下一章）

三、获取研发网账号与 apiKey（必做）

本步骤参考 研发网登录教程.pdf。每个客户端启动前都需要先获取自己的 apiKey。

  1. 登录研发网控制台

  2. 创建 apiKey

    • 登录后进入控制台，选择"创建 apiKey"。
    • 创建完成后，点击"复制"将 apiKey 复制到剪贴板。
    • apiKey 形如：AK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  3. 记录网络密钥（network-key）

    • 在控制台查看当前要加入的网络，记录其 network-key（如 XYJQ97TJ、B253FA86、53265B8F）。
    • 若不配置 network-key，启动时会提示选择网络。

  4. 保留好上述两个值，下一步写入 config.yml。

四、配置 config.yml

打开目录下的 config.yml，按下表替换关键字段：

link:
  network-key: XYJQ97TJ          # 第三步获取的网络密钥
  # tun:
  #   mtu: 1300                  # 虚拟网卡 MTU，默认 1300，按需调整

app:
  background: false              # true：后台运行（Windows 隐藏控制台）

http:
  url: http://119.45.35.205:48088/api
  token: AK-xxxxxxxxxxxxxxxxxxxx # ★ 替换为第三步复制的 apiKey ★

# 可选：端口转发规则（在虚拟 IP 上监听，不会暴露到物理网卡）
portForward:
  enabled: true
  rules:
    - proto: tcp
      targetHost: 192.168.10.41  # 转发目标
      listen: 22                 # 虚拟 IP 上监听的端口
      targetPort: 422            # 目标端口

字段说明

字段说明
link.network-key控制台获取的网络密钥；不填则启动时交互式选择
app.background是否后台运行（仅 Windows 生效，隐藏控制台窗口）
http.url研发网 API 地址，一般无需修改
http.token必填，替换为个人的 apiKey
portForward.rules[]端口转发规则，详见第七章

五、Windows 部署

5.1 方式 A：GUI 启动器（推荐桌面用户）

  1. 确保本机已安装 JRE 17+（命令行执行 java -version 验证）。
  2. 右键 LinkLoom.exe → "以管理员身份运行"。
    • 安装虚拟网卡需要管理员权限。
  3. 启动成功后会在系统托盘显示图标，并在控制台输出虚拟 IP。

5.2 方式 B：一键脚本（推荐命令行）

双击 启动.bat，或在 PowerShell 中执行：

cd C:\Users\33043\OneDrive\Desktop\tesgt
.\启动.bat

脚本会：

  • 自动请求 UAC 提权；
  • 在当前目录查找 *.jar；
  • 使用 java -Dhttps.protocols=TLSv1.2 -jar 启动。

如需后台运行，将 config.yml 中的 app.background 改为 true。

5.3 设为开机自启动（Windows）

两种方式任选其一：

  • 方式 1：把 LinkLoom.exe 的快捷方式放入 shell:startup（开始菜单输入即可打开）。
  • 方式 2：使用任务计划程序（Task Scheduler），触发条件设为"登录时"，操作为运行 启动.bat，并勾选"使用最高权限运行"。

六、Linux 部署（systemd 服务）

Linux 下提供两个脚本，按需选择：

  • deploy.sh：功能完整，自动检测并下载 JRE，适合全新服务器。
  • register_service.sh：精简版，仅注册 systemd 服务，要求系统已安装 Java。

6.1 上传交付包

将整个 tesgt 目录上传到目标服务器，例如 /opt/linkloom/：

# 本地 -> 服务器
scp -r tesjt user@server:/opt/linkloom

ssh user@server
cd /opt/linkloom

6.2 方式 A：一键部署（推荐）

chmod +x deploy.sh
sudo ./deploy.sh

脚本执行流程：

  1. 校验 root 权限、systemd 可用性、JAR 与 config.yml 是否存在；
  2. 检测 Java：优先使用 ./jre/ 下的内置 JRE，其次使用系统 Java；
  3. 若均无 Java，提示是否自动下载 Adoptium Temurin JRE 17（输入 y 确认）；
  4. 停止旧版本服务（如存在）；
  5. 写入 /etc/systemd/system/linkloom-app.service；
  6. daemon-reload → enable → start；
  7. 打印状态与常用管理命令。

仅安装 JRE（不部署服务）：

sudo ./deploy.sh --install-jre

6.3 方式 B：精简注册（已有 Java）

chmod +x register_service.sh
sudo ./register_service.sh install    # 注册并启动（默认动作）
sudo ./register_service.sh status     # 查看状态
sudo ./register_service.sh uninstall  # 停止并卸载

6.4 systemd 服务管理命令

服务名默认为 linkloom-app（deploy.sh）或 app-1.1.1（register_service.sh），以实际脚本中的 SERVICE_NAME 为准。

systemctl status  linkloom-app        # 查看状态
systemctl start   linkloom-app        # 启动
systemctl stop    linkloom-app        # 停止
systemctl restart linkloom-app        # 重启
journalctl -u linkloom-app -f         # 实时系统日志
tail -f /opt/linkloom/logs/app.log    # 实时应用日志
systemctl disable linkloom-app        # 取消开机自启

修改 config.yml 后只需 systemctl restart linkloom-app 即可生效。

七、macOS 部署（launchd 服务）

macOS 使用 start_jar.sh 控制进程，并可选通过 com.user.yourapp.plist 注册为开机自启服务。

7.1 启动脚本

chmod +x start_jar.sh
./start_jar.sh start     # 启动（后台）
./start_jar.sh stop      # 停止
./start_jar.sh restart   # 重启
./start_jar.sh status    # 查看运行状态
./start_jar.sh logs      # 实时查看日志（tail -f）

使用前请先修改 start_jar.sh 中的 JAR_PATH 为本机真实路径。

7.2 注册为开机自启服务

  1. 复制模板：

    cp com.user.yourapp.plist ~/Library/LaunchAgents/com.user.linkloom.plist

  2. 编辑 ~/Library/LaunchAgents/com.user.linkloom.plist，替换占位符：

    <key>ProgramArguments</key>
<array>
    <string>/bin/bash</string>
    <string>/opt/linkloom/start_jar.sh</string>   <!-- 改为实际路径 -->
    <string>start</string>
</array>
...
<key>WorkingDirectory</key>
<string>/opt/linkloom</string>                    <!-- 改为实际目录 -->
...
<key>EnvironmentVariables</key>
<dict>
    <key>JAVA_HOME</key>
    <string>/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home</string>
</dict>

  3. 加载 / 卸载：

    launchctl load   ~/Library/LaunchAgents/com.user.linkloom.plist   # 加载并启动
launchctl unload ~/Library/LaunchAgents/com.user.linkloom.plist   # 停止并卸载
launchctl list | grep linkloom                                     # 查看状态

日志默认输出到 /tmp/yourapp.stdout.log 与 /tmp/yourapp.stderr.log，可在 plist 的 StandardOutPath / StandardErrorPath 中自定义。

八、端口转发（可选独立服务）

端口转发/ 目录提供独立的端口转发服务（与主程序的 portForward 互不影响），用于在没有运行完整 LinkLoom 客户端的机器上把流量中继到隧道对端。

8.1 配置 端口转发/port-forward.yml

enabled: true

rules:
  - proto: tcp
    listenIp: 0.0.0.0          # 监听 IP，0.0.0.0 表示所有网卡
    listen: 2222               # 监听端口
    targetHost: 10.0.57.6      # 隧道对端虚拟 IP
    targetPort: 22             # 目标端口

示例场景：本机物理 IP 192.168.10.41，同局域网同事访问隧道对端 10.0.57.6:22 的 SSH：

ssh -p 2222 user@192.168.10.41

前提：本机已在跑 LinkLoom 客户端，且 OS 路由能把 10.0.57.6 走 TUN 网卡。

8.2 启动（Windows）

cd 端口转发
.\start.bat                 # 前台运行
.\start.bat start           # 后台运行（生成 logs\app.pid）
.\start.bat stop            # 停止
.\start.bat status          # 查看状态

8.3 启动（Linux / macOS）

cd 端口转发
chmod +x start.sh
./start.sh                  # 详见脚本内说明

九、运维 FAQ

Q1：启动报错"未找到 Java / Java 版本过低" A：执行 java -version 确认版本 ≥ 17。Linux 可 sudo ./deploy.sh --install-jre 自动安装；Windows 推荐安装 Temurin / Liberica JRE 17。

Q2：启动后无法连接研发网 A：

  1. 检查 config.yml 中 http.token 是否为本人的最新 apiKey；
  2. 检查 network-key 是否正确（不填则启动时交互选择）；
  3. 查看日志：Linux journalctl -u linkloom-app -f 或 tail -f logs/app.log；Windows 查看控制台 / logs/linkloom.log。

Q3：升级 JAR 包 A：

  1. 备份旧包：cp app-1.1.1.jar app-1.1.1.jar.bak；
  2. 替换 app-1.1.1.jar；
  3. 重启服务：Linux systemctl restart linkloom-app，Windows 关闭控制台后重新运行 启动.bat。

Q4：Windows 提示"需要管理员权限" A：启动.bat 已内置 UAC 自动提权；若被拦截，请右键 → "以管理员身份运行"。安装 TUN 虚拟网卡必须管理员权限。

Q5：如何切换网络 / apiKey 失效？ A：登录 https://link.ahwulian.com.cn/ 重新创建 apiKey，替换 config.yml 中的 http.token 字段后重启服务即可。

Q6：日志太大如何清理？ A：日志按天滚动（logs/linkloom.YYYY-MM-DD.0.log），可定期删除历史日志；当前活跃日志 linkloom.log 不可直接删除，停服后再清理。

十、参考资源

文档基于交付包现有脚本整理，如脚本升级请同步更新本说明。

最近更新: