安装 Agent
Agent 装在你要接入的那台内网机器上。目前提供手动安装：拿到单文件二进制后，用一条命令把它接成系统服务。
一键安装脚本即将提供。到目前为止我们还没有发布任何可以直接下载并执行的安装脚本，首页上曾经出现过的那条
curl … | sh 形式的命令请不要使用：它指向的地址上没有脚本，把那个地址上的内容管道给 sh 不会安装任何东西。如果你之前复制过它，请以本页为准。一、支持的系统与前提
Agent 目前只支持两种落地形态，两种都要求它所在的主机能访问控制面（HTTPS 出网）。
| 平台 | 是否支持 | 服务管理方式 | 前提 |
|---|---|---|---|
| Linux | 支持 | systemd |
需要 root；需要有 systemd；systemd unit 默认落在 /etc/systemd/system/securelink-agent.service（可用参数改路径）。日志走 journald。 |
| Windows | 支持 | Windows 服务（SCM） | 注册/注销服务需要管理员权限；服务默认随机器自启，也可注册为手动启动。只看预览不需要管理员。 |
| macOS | 不支持作为 Agent 主机 | — | Agent 的系统服务形态只有上面两种。在 macOS 上执行安装命令会明确返回「不支持」，而不是假装装成功。macOS 可以作为成员设备使用（走官方 WireGuard 客户端）。 |
| 容器 | 另有形态，文档即将提供 | 容器编排 | 编排产物已经在仓库里，但面向公众的容器部署说明还没写完，因此本页不给出具体步骤。 |
二、Linux（systemd）
先把 securelink-agent 二进制放到目标机器上（单文件，没有外部依赖），然后：
# 先预览：只打印将要写入的 unit 内容，不落盘、不改系统（这一步不需要 root）
securelink-agent install --dry-run
# 确认无误后真正安装（生成 unit + enable + start）——完整步骤见第四节
sudo -E securelink-agent install为什么是 sudo -E：Agent 的配置来自环境变量，install 会把当前进程里的这些变量捕获进服务定义；不带 -E 的话 sudo 会把环境清空，结果是一个「装好了但连不上控制面」的服务。真正要装之前，请先照第四节的完整步骤把变量设好——否则预览里看到的 unit 会缺配置。
常用参数：
--unit-path：unit 文件落点，默认/etc/systemd/system/securelink-agent.service。--user：以哪个用户运行服务。--env 变量名=值：指定或覆盖一个配置项，可重复；优先于当前环境里的同名变量。变量名见第四节的表。--no-env-capture：不自动捕获当前环境，只装用--env显式给出的那些。
排障用 journalctl -u securelink-agent 看日志——Linux 形态的日志只进 journald，不会再另写一份文件。
三、Windows 服务
在管理员 PowerShell 或 CMD 里执行（securelink-agent.exe 换成实际文件名）：
# 1. 先预览计划（这一步不需要管理员）
.\securelink-agent.exe install-service --dry-run
# 2. 注册为随机器自启的 Windows 服务
.\securelink-agent.exe install-service --start auto常用参数：
--start auto|manual：随机器自启，或只在手动启动时运行。--name：服务名（会写进服务启动参数，运行侧据此派发，所以卸载时要给同一个名字）。--display-name/--description：在services.msc里显示的名字与说明。--env 变量名=值/--no-env-capture：与 Linux 相同。
Windows 服务没有可拷走的预览产物，所以
install-service 只有 --dry-run（打印计划）与真安装两种；反过来，Linux 的 systemd unit 是纯文本，你完全可以在一台 Windows 工作站上 --dry-run 生成内容，再拷到目标 Linux 机器上。四、配置怎么传给 Agent
Agent 只读环境变量。下表是它认识的全部变量：名称就是安装时真正要用的名字，值要么由我们给出，要么由你自己的账号或部署决定。
| 变量名 | 值从哪来 | 类型 / 是否必填 |
|---|---|---|
SAAS_ENDPOINT |
控制面（gRPC）地址。公测环境用 https://console.sclink.dev:9443；自建部署填你自己那个 Agent 能连上的地址。 |
URL（https://主机[:端口]，不带端口按 443 算）。必填 |
TENANT_UID |
你的租户标识：登录控制台后看左侧栏租户名下方那一串，可选中复制。格式是 t_ 开头的 14 位。 |
标识。必填 |
ENROLLMENT_TOKEN_FILE |
注册 Token 所在的文件路径（不是 Token 本身）。Token 在控制台开通引导页点「生成注册令牌」得到，明文只显示一次；把它写进这个文件，Agent 自己去读。 | 路径。首次入网必填；已注册过的机器可以没有 |
SIGNING_KEY_FILE |
控制台给出的签名公钥（只有公钥，私钥永远在管理员浏览器里）。存成文件，填它的路径。 | 路径。必填（缺了 Agent 起不来） |
SIGNING_KEY_ID |
这枚签名公钥的 ID，与公钥来自同一处。自建部署如果没有改名，就是 trk_root；控制台里能查到当前 active 的那个值。 |
字符串。必填 |
RELAY_ENDPOINT |
打洞辅助（中继）的主机名，只写主机名，不带端口和协议（协商端口由平台定死为 51920）。控制台在设备配置里给出的就是这个主机名。 | 主机名。中继模式下必填 |
SAAS_CA_FILE |
用来校验控制面 TLS 证书的 CA 证书（PEM）。控制面用公有 CA 签证书时可以不填（退回系统根证书）。 | 路径。选填 |
传入方式按优先级从低到高：
- 安装时环境里已有的变量（
install自动搬运的就是上表这些名字的变量）； --env 变量名=值显式指定的值。例如--env TENANT_UID=t_2f8a1c4b9d3e、--env LOG_LEVEL=debug（上表没列的LOG_LEVEL、AGENT_DATA_DIR、WG_INTERFACE等也接受，都有默认值）。
注册成功后，Agent 会以证书方式维持与控制面的长连接，不会继续使用注册 Token 重连——所以 Token 过期不会让一台已注册的 Agent 掉线。
照抄就能用的完整步骤（Linux）
把 securelink-agent 二进制放到目标机器后，在同一个 shell 里从上到下执行。控制台那一页给出的注册 Token 与签名公钥需要你替换两处路径与内容，其余原样可用：
# 0. 放密钥文件的目录（下面两个文件都放这里）
sudo mkdir -p /etc/securelink
# 1. 注册 Token：把控制台「开通引导」页给出的令牌明文写进文件（明文只显示一次）
umask 077
sudo tee /etc/securelink/enrollment_token >/dev/null
# 粘贴令牌后按 Ctrl-D 结束
# 2. 签名公钥：把控制台给出的公钥内容写进文件（只有公钥，没有私钥）
sudo tee /etc/securelink/signing_key.pub >/dev/null
# 粘贴公钥后按 Ctrl-D 结束
sudo chmod 600 /etc/securelink/enrollment_token /etc/securelink/signing_key.pub
# 3. 告诉 Agent 要去哪、是谁（TENANT_UID 从控制台左侧栏复制）
export SAAS_ENDPOINT=https://console.sclink.dev:9443
export TENANT_UID=粘贴从控制台左侧栏复制的租户标识
export ENROLLMENT_TOKEN_FILE=/etc/securelink/enrollment_token
export SIGNING_KEY_FILE=/etc/securelink/signing_key.pub
export SIGNING_KEY_ID=trk_root
export RELAY_ENDPOINT=relay.sclink.dev
# 4. 先预览（这一步不改系统）
sudo -E securelink-agent install --dry-run
# 5. 确认预览里 Environment= 的每一项都对，再真装
sudo -E securelink-agent installSAAS_ENDPOINT 必须是 https，而且指向 Agent 的 gRPC 入口——它和控制台网页不是同一个入口。公测环境请带 :9443；漏了端口会默认连 443，表现为 Agent 一直注册不上。
如果
上表里其余变量照此逐个加。装完用
sudo -E 没能把变量带进去（部分系统的 sudoers 会清环境），install 会在 stderr 上以「服务定义里的环境变量不足以让 Agent 启动」列出缺哪几个——此时用 --env 逐个补即可，例如：sudo securelink-agent install --env SAAS_ENDPOINT=https://console.sclink.dev:9443 --env TENANT_UID=t_2f8a1c4b9d3e上表里其余变量照此逐个加。装完用
systemctl status securelink-agent 与 journalctl -u securelink-agent -n 50 确认。照抄就能用的完整步骤（Windows）
在管理员 PowerShell 里执行。securelink-agent.exe 换成实际文件名与路径：
# 1. 注册 Token（第 1 行粘贴控制台给出的令牌明文，明文只显示一次）
New-Item -ItemType Directory -Force C:\ProgramData\SecureLink | Out-Null
Set-Content -NoNewline -Encoding ascii C:\ProgramData\SecureLink\enrollment_token -Value 粘贴令牌明文
# 2. 签名公钥（粘贴控制台给出的公钥内容；只有公钥）
Set-Content -NoNewline -Encoding ascii C:\ProgramData\SecureLink\signing_key.pub -Value 粘贴公钥内容
# 3. 告诉 Agent 要去哪、是谁（TENANT_UID 从控制台左侧栏复制）
$env:SAAS_ENDPOINT = 'https://console.sclink.dev:9443'
$env:TENANT_UID = '粘贴从控制台左侧栏复制的租户标识'
$env:ENROLLMENT_TOKEN_FILE = 'C:\ProgramData\SecureLink\enrollment_token'
$env:SIGNING_KEY_FILE = 'C:\ProgramData\SecureLink\signing_key.pub'
$env:SIGNING_KEY_ID = 'trk_root'
$env:RELAY_ENDPOINT = 'relay.sclink.dev'
# 4. 先预览（不需要管理员）
.\securelink-agent.exe install-service --dry-run
# 5. 确认预览里要写入的环境变量都对，再真装
.\securelink-agent.exe install-service --start autoWindows 的用法与 Linux 只有两点差别：变量写成 $env:名字，以及上面的 install-service 把环境变量写进服务注册表（HKLM\SYSTEM\CurrentControlSet\Services\服务名\Environment），所以同样要在同一个 PowerShell 窗口里执行第 3 步到第 5 步。
签名公钥是必需的，不是可选项。Agent 启动时会先读
SIGNING_KEY_FILE 并加载验签公钥——文件不存在或内容不是一枚 Ed25519 公钥（Base64 或 hex），进程会直接以「invalid configuration / read signing key file」退出；装成服务后表现为服务反复重启。注册 Token 文件则相反：已注册过的机器可以没有它。五、卸载
Linux 与 Windows 各有一条对应的卸载命令：
# Linux：停止并移除 unit（保留数据目录）
sudo securelink-agent uninstall
# Linux：连本地数据一起删（不可逆）
sudo securelink-agent uninstall --purge
# Windows：停止并注销服务
.\securelink-agent.exe uninstall-serviceuninstall 默认不删数据目录，这是刻意的：重装时不必重新注册。--purge 才会把本地数据一起清掉，执行前请确认。
六、装完之后
- 回到控制台，Agent 应显示为在线。它注册时会一并上报控制面需要的公钥信息，管理员批准设备时会用到。
- 打洞辅助模式下，Agent 还会向端点发现服务发起探测并把探测到的可达端点上报；端点协商成功之后，成员设备拿到的配置里才会有可用的服务端地址。如果没有，控制台会明确告诉你「打洞辅助服务不可用（无法完成端点协商）」，而不是给你一个编出来的地址。
- 连不通、Agent 一直离线、设备一直待批准：见常见问题。