Agent 安装与卸载 | DitOps 点脉运维

Agent 安装在每台被管理设备上，托盘常驻，负责资产采集、运行状态上报与远程协助。

1. 安装之前

项	要什么
绑定码	由 IT 管理员在管理端「设置 → 组织信息 → 设备绑定码」获取，形如 `123456-7890`（前 6 位企业码 + 后 4 位组织绑定码）
新设备开关	该组织没有暂停新设备加入，否则绑定会被拒绝
网络	设备能访问企业服务器地址（HTTPS 与 WSS，与 Edge Functions 同域）

绑定码一台设备只用一次。已经绑定过的设备不要重复输入，否则会多出一条设备记录；需要迁到另一家企业时，由管理员在管理端对该设备下发「换绑企业」并输入目标企业绑定码（设备需在线，且 Agent 为 1.2.165 及以上）。

2. Windows

从官网下载 desktop_agent-latest.zip，解压后双击里面的 desktop_agent-windows-<版本>-<构建>.exe。
向导里的「安装为系统服务」是勾选且不可修改的灰色状态：安装 Agent 就会安装系统服务，这一项只是告知。安装到那一步会单独请求一次管理员授权（UAC），同意即可。
完成后程序自动启动，输入绑定码。

官网发 zip 是因为浏览器会拦未签名的 exe：下载时提示「不常下载」选「保留」；解压后首次运行若弹出「Windows 已保护你的电脑」，点「更多信息 → 仍要运行」。域策略 / MDM 直接推 exe，不经过浏览器。
安装位置：%LOCALAPPDATA%\Programs\DitOps Agent（按当前用户安装，安装程序本身不需要管理员权限）。
若第 2 步拒绝了 UAC：程序照常可用，但锁屏或注销后不再采集。请管理员在管理端对该设备下发「切换为服务模式运行」补上。

批量静默安装（域策略 / MDM，以 SYSTEM 或管理员身份运行）：

desktop_agent-windows-<版本>-<构建>.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /ALLUSERS /BINDINGCODE=123456-7890

/ALLUSERS 装进 C:\Program Files\DitOps Agent，本机所有用户可用。安装程序本身已提权，服务那一步不会再弹 UAC，所以壳与服务一次装完。
/BINDINGCODE 把绑定码预置给守护进程，装完几十秒内自动绑定，不用一台台输码。码写错不会让安装失败：目录判「绑定码错误」4 次后文件被改名为 binding_code.rejected.txt、设备停止重试，改正后重新写入 binding_code.txt 即可；整家企业连续错 5 次会暂停接受新设备 10 分钟，下发前先在管理端核对一遍码。
以普通用户身份静默装、确认不了 UAC 时，才需要加 /TASKS=!installservice 跳过服务；装完再由管理员在管理端下发一次「切换为服务模式运行」。

按机器装过的机器，应用内自动更新拿不到提权会中止（已装版本照常可用）；升级由 MDM 重新下发同一条命令。

3. macOS

macOS 只提供 pkg 安装包（DMG 已下线，不再提供）：

双击 desktop_agent-macos-<版本>-<构建>.pkg（官网下载的是 desktop_agent-latest.pkg），安装过程中输入一次管理员密码。
装完应用、后台服务（LaunchDaemon）与开机自启一次就位，应用随即启动，输入绑定码。

pkg 已签名并公证，双击即可通过系统校验，不需要右键「打开」或在「隐私与安全性」里放行。装好后即使没有人登录也会持续采集。

之后的升级不需要任何密码：守护进程查到新版本会以 root 自行安装同一份 pkg，壳与后台服务一起换掉（见第 5 节）。

批量部署 / MDM：用的还是这同一个 pkg，不需要有人在机器前点授权。installer -pkg xxx.pkg -target / 或 MDM 推完后，在安装后脚本里写入 /Library/Application Support/DitOpsAgent/binding_code.txt（内容为绑定码，写完 chmod 600），守护进程 30 秒内自行绑定。

4. Linux

Linux 桌面端（当前为 x86_64）提供三种安装包，装出来是同一个程序，按发行版任选一种：

系统要求：glibc ≥ 2.18（Debian 10+ / Ubuntu 18.04+ / RHEL、CentOS Stream 8+）。CentOS 7 / RHEL 7 只有 glibc 2.17，Agent 由 Dart 编译、跑不起来，装上去会报 GLIBC_2.18 not found。

Linux 三种安装包

4.1 .deb

sudo apt install ./desktop_agent-latest-x86_64.deb

依赖（GTK3、libblkid、liblzma、AppIndicator）由 apt 自动安装。
若用 dpkg -i 安装后提示缺依赖，执行 sudo apt -f install 补齐。
装完后应用菜单里是「点脉运维·桌面端」，命令行是 ditops-desktop-agent。

4.2 .rpm

sudo dnf install ./desktop_agent-latest-x86_64.rpm       # Fedora / RHEL 8+ / CentOS Stream 8+

托盘库 libayatana-appindicator3.so.1 在 RHEL / CentOS 上来自 EPEL，先 sudo dnf install epel-release。
openSUSE：sudo zypper install ./desktop_agent-latest-x86_64.rpm。

4.3 .tar.gz

# Debian / Ubuntu
sudo apt install libgtk-3-0 libblkid1 liblzma5 libayatana-appindicator3-1
# RHEL / Fedora（EPEL）
sudo dnf install gtk3 libblkid xz-libs libayatana-appindicator-gtk3

tar -xzf desktop_agent-latest-x86_64.tar.gz
cd ditops-desktop-agent
./desktop_agent

解压到哪就从哪运行，不写系统目录，也不会安装桌面菜单项。

4.4 装成系统服务

Linux 桌面版的管理端指令与 Windows / macOS 相同：设备 → 远程指令 →「切换为服务模式运行」。需要桌面会话（会弹一次授权框），SSH 登录或无桌面会话时无法完成。

装好后采集、上报与远程指令由 root 的守护进程负责，壳只保留界面：

Linux 上的壳与守护进程

内容	界面（登录用户）	守护进程（root）
程序	`/opt/ditops-desktop-agent/desktop_agent`	`/var/lib/ditops-agent/ditops-agent`
数据	`~/.local/share/cn.ditops.desktopAgent`	`/var/lib/ditops-agent`
日志	数据目录下的 `log/ditops_agent_*.log`	`/var/lib/ditops-agent/log/ditops_daemon_*.log`
自启	登录时自动启动	systemd `ditops-agent.service`

常用命令：systemctl status ditops-agent、journalctl -u ditops-agent -n 100。

4.5 服务器版（无图形界面）

没有图形界面的 Linux 服务器不需要上面三个桌面包，改用服务器版：只有守护进程，不依赖 GTK，装完由 systemd 托管、开机自启，不需要任何人登录。

一条命令装完（自动识别架构并下载安装包、装好服务、写入绑定码并等它绑上；官方当前只发布 x86_64 包，aarch64 用 --pkg 指定自建包）：

curl -fsSL https://downloads.ditops.cn/linux/agent/install-agent-server.sh | sudo bash -s -- --code 123456-7890

系统要求同本章开头：glibc ≥ 2.18、systemd 在跑。脚本在下载之前就查这些，不满足会直接退出并说明原因。
--code 换成这台设备的绑定码。不给也能装，只是先不绑定（之后写 binding_code.txt 或重跑脚本即可）。
脚本可重复执行：已装的原地升级，已绑定的不会重绑。
安装包也可以自己指定：--pkg ./ditops-agent-…（本地文件）或 --url https://…（内网源）；同目录下只有一个 ditops-agent-* 包时会自动用它。
覆盖配置：/etc/ditops-agent/agent.env（KEY=VALUE 格式，改完 systemctl restart ditops-agent）。

不想用脚本时手动装：.tar.gz 解压后 sudo ./ditops-agent/install.sh，或 sudo apt install ./ditops-agent_*.deb / sudo dnf install ./ditops-agent-*.rpm。绑定没有对话框，把绑定码写进文件即可：

echo '123456-7890' | sudo tee /var/lib/ditops-agent/binding_code.txt
sudo chmod 600 /var/lib/ditops-agent/binding_code.txt

守护进程会在 30 秒内读取并完成绑定，随后删除该文件。

服务器版与桌面版不要装在同一台机器上：两者共用同一个 systemd 服务名与数据目录。

5. 升级

保持默认设置时，Agent 会在管理端发布新版本后自行下载并安装，无需人工干预，也不需要任何人输入密码（macOS 上是守护进程以 root 安装同一份 pkg，壳与后台服务一起替换）。

也可以手动升级：重新安装新版本的安装包即可，绑定关系与本地数据都会保留。系统服务（守护进程）的二进制单独更新；若长期不生效，macOS 重装一次官网那份 pkg，Linux 在管理端先「切换为用户模式运行」再「切换为服务模式运行」重装一次。

6. 卸载

顺序不能反：先卸后台服务（或直接远程卸载 Agent），再卸程序。

Windows：管理员在管理端对这台设备下发「远程命令 → 卸载 Agent」一次即可（要求守护进程 1.2.177 及以上、以服务形态运行），程序目录、后台服务、开机自启项、卸载登记与开始菜单快捷方式一并清掉；对话框里可选「同时删除本机用户数据」，不勾选则缓存、会话与 AI 记忆保留（只是程序没了，重装后可直接接上）。按用户装法下这些登记分散在每个用机人自己的账户里，会逐个账户清。手动卸载：设置 → 应用 → DitOps Agent → 卸载。
macOS：管理员在管理端对这台设备下发「远程命令 → 卸载 Agent」一次即可，应用、后台服务、系统级自启项与安装登记一并清掉；对话框里可选「同时删除本机用户数据」，不勾选则缓存、会话与本地绑定保留（只是程序没了，重装后可直接接上）。手动卸载的顺序是：管理端「切换为用户模式运行」（会一并清掉 LaunchDaemon 与 /Library/Application Support/DitOpsAgent 里的后台程序）→ 删掉系统级的托盘自启项 sudo rm -f /Library/LaunchAgents/com.ditops.agent.shell.plist → 把应用拖进废纸篓（进程随注销或重启退出）。直接删除应用会留下开机报错的后台服务。
Linux（deb/rpm）：管理员在管理端对这台设备下发「远程命令 → 卸载 Agent」一次即可（要求守护进程 1.2.178 及以上、以服务形态运行），systemd 服务、守护进程数据目录、桌面程序的安装目录与各用户的自启项一并清掉；对话框里可选「同时删除本机用户数据」，不勾选则缓存、会话与本地绑定保留。手动卸载：sudo apt remove ditops-desktop-agent 或 sudo dnf remove ditops-desktop-agent；tar.gz 安装的直接删除解压目录，并删除 ~/.local/share/cn.ditops.desktopAgent 与 ~/.config/autostart/cn.ditops.desktopAgent.desktop。
服务器版：用对应包管理器卸载，或运行安装包里的 uninstall.sh。

/etc/ditops-agent/agent.env 会被保留，需要时手动删除。设备记录不会随之删除，请在管理端移除该设备。

7. 常见问题

现象	原因与处理
绑定失败：无效或已过期	绑定码抄错、不是该企业的码，或组织暂停了新设备加入
启动报 `libayatana-appindicator3.so.1` 找不到	托盘库未安装（tar.gz 常见），按 4.3 补依赖
托盘没有图标	GNOME 需要 AppIndicator 扩展，Ubuntu 默认已带
「切换为服务模式运行」无反应	授权弹窗被其他窗口挡住；SSH 或无桌面会话的机器请改用服务器版
服务起不来	`journalctl -u ditops-agent -n 100`；常见原因是 `agent.env` 写成了 `KEY = VALUE`（应为 `KEY=VALUE`，不加引号）
管理端出现两台同名设备	重复绑定过，删除多余那台
远程卸载后设备还在列表里	卸载只删机器上的程序，设备记录不随之下线；需要时在管理端移除该设备