Appearance
IM Synology Login Plugin 企微群晖套件
IM Synology Login Plugin 是安装在群晖 DSM 上的本机套件。它负责连接云端 IM 配置服务，主动拉取用户和群组同步任务，并在 NAS 本机执行 synouser、synogroup 命令。
套件采用主动拉取模式。云端服务不需要访问办公室内网 NAS，只要 NAS 能访问云端服务即可。
套件的正式组件名是 IM Synology Login Plugin。部分截图或当前 SPK 元信息里可能显示“必码IM配置套件”，指的是同一个群晖本机套件。
套件职责
text
云端 IM 配置服务生成任务
-> 群晖套件主动拉取任务
-> NAS 本机执行用户和群组命令
-> 套件回传执行结果套件页面提供：
text
服务 URL 地址
套件密钥
套件监听地址
只演练模式
测试云端连接
立即拉取 1 个任务
云端全量同步并执行
源码结构
text
im-synology-login-plugin/
├── INFO Synology SPK 元信息
├── conf/privilege 套件权限配置
├── package-scripts/ DSM 启停脚本
├── src/ Go Agent 工程
├── ui/auto-sso.html DSM 同源自动 SSO 入口
├── grant-root.sh root 授权脚本
└── scripts/package-spk-local.sh 本地打包脚本本地打包
先跑测试：
bash
cd src
go test ./...回到项目根目录打包：
bash
./scripts/package-spk-local.sh默认产物：
text
release/im-synology-login-plugin_1.0.1_x86_64.spk其他 CPU 架构需要同时设置 SPK_ARCH 和 AGENT_GOARCH，例如：
bash
SPK_ARCH=armv8 AGENT_GOARCH=arm64 ./scripts/package-spk-local.sh如果不确定 NAS 架构，先在 DSM 控制面板或 SSH 中确认 CPU 类型，再选择对应架构打包。
获取 SPK 包
有两种方式：
- 开发者本地从源码打包，产物在
release/目录。 - 如果云端管理后台已经提供“下载套件”页面，也可以直接下载当前推荐版本。
不管用哪种方式，最终拿到的都是 .spk 文件，然后在 DSM 套件中心手动安装。
手动安装
DSM 操作：
text
套件中心 -> 手动安装 -> 上传 im-synology-login-plugin_1.0.1_x86_64.spk安装完成后在套件中心可以看到：
text
IM Synology Login Plugin / 必码IM配置套件
开发者：北京必码科技工作室安装完成后先不要急着同步用户。先完成 root 授权、套件配置和云端自检。
授权 root 权限
套件默认按普通第三方套件安装。要创建、更新或禁用 DSM 用户和群组，必须让套件以 root 身份运行。
推荐使用 DSM 任务计划执行：
- 打开 DSM「控制面板」。
- 进入「任务计划」。
- 新增「计划的任务」->「用户定义的脚本」。
- 用户账号选择
root。 - 用户定义脚本填写：
bash
sh /var/packages/im-synology-login-plugin/target/var/grant-root.sh- 保存任务并手动运行一次。
- 回到套件中心，重新启动本套件。
也可以 SSH 登录 NAS 后执行：
bash
sudo -i
sh /var/packages/im-synology-login-plugin/target/var/grant-root.sh验证运行身份：
bash
PID="$(cat /var/packages/im-synology-login-plugin/target/var/agent.pid)"
cat /proc/${PID}/status | grep '^Uid:'正常第一列应该是 0。如果不是 0，说明授权没有生效，或者授权后没有重启套件。
打开套件配置页
在 DSM 套件中心点击本套件的“打开”按钮即可进入配置页。如果没有显示打开按钮，可以直接访问 NAS 本机监听端口。
内网访问：
text
http://NAS内网IP:25323/例如：
text
http://192.168.1.30:25323/外网访问建议通过 DSM 反向代理：
text
来源：https://plugin.example.com:4433
目标：http://192.168.1.30:25323不要把 nas.example.com:4433 和 plugin.example.com:4433 混用。前者通常是 DSM 自身入口，后者才是套件配置页入口。
配置套件
页面填写：
text
服务 URL 地址：
https://im-login-server.example.com
套件密钥：
首次打开自动生成；保存后复制到云端服务的“群晖套件 / 套件密钥”
套件监听地址：
:25323
只演练：
测试阶段可以开启，正式同步前关闭保存后点击：
text
测试云端连接如果成功，再回到云端服务执行“集成自检”。
套件密钥的方向不要弄反：密钥由 NAS 套件生成，复制到云端服务；不是云端服务生成后再填回 NAS。
截图右侧的运行状态是安装后最重要的检查区。正式同步前至少确认：
text
配置状态：已配置
自动拉取：运行中
运行身份：root
测试云端连接：成功DSM 同源自动 SSO
套件会提供一个 DSM 同源页面：
text
https://nas.example.com:4433/webman/3rdparty/im-synology-login-plugin/auto-sso.html这个页面不是套件配置后台，而是企业微信工作台自动登录使用的入口。它运行在 DSM / Drive 同一个域名下，会自动调用 DSM 自己的 OIDC 初始化接口：
text
/index.cgi?action=oidcauthurl&method=oidc典型流程：
text
企业微信工作台
-> 云端 /dsm?client_id=<oidc.client_id>
-> DSM 同源 auto-sso.html
-> DSM OIDC
-> 企业微信授权
-> 回到 DSM用户看到的过渡页类似这样：
安装或升级 SPK 后，先在浏览器访问 auto-sso.html 地址验证：
text
能自动跳到云端 SSO / 企业微信授权：DSM 同源入口已生效
返回 404：DSM 没有生成 3rdparty 链接，重启套件或重新安装
提示 DSM 未返回 SSO 地址：DSM OpenID Connect SSO 还没有配置好执行同步
配置完成后可以在套件页面执行：
text
立即拉取 1 个任务
云端全量同步并执行正式同步建议顺序：
- 云端后台选择企业微信部门同步范围。
- 套件页面确认“运行身份”为
root。 - 套件页面“测试云端连接”成功。
- 先打开“只演练”执行一次同步。
- 确认任务和日志正常后关闭“只演练”。
- 执行全量同步。
- 到 DSM 控制面板检查用户和群组。
日志和配置文件
日志：
text
/var/packages/im-synology-login-plugin/target/var/agent.log查看日志：
bash
tail -f /var/packages/im-synology-login-plugin/target/var/agent.log配置文件：
text
/var/packages/im-synology-login-plugin/target/var/agent.env通常不需要手动编辑配置文件，优先使用套件页面保存。
验证标准
套件侧：
text
套件中心显示已启动
套件页面显示已配置
运行身份显示 root
测试云端连接成功
立即拉取任务可以返回成功或“没有待处理任务”云端侧：
text
集成自检中 synology.agent_secret 通过
通讯录同步任务状态变为 success
日志中心可以看到 Agent 任务结果DSM 侧：
text
用户与群组中出现企业微信同步用户
禁用企业微信成员后 DSM 用户被禁用
企业微信工作台可进入 DSM 登录流程登录完成后应进入 DSM 桌面。
常见问题
外网打不开套件配置页
优先检查：
text
DSM 反向代理来源域名是否是 plugin.example.com:4433
目标地址是否是 http://NAS内网IP:25323
套件是否已启动
NAS 本机是否能访问 http://127.0.0.1:25323
路由器或防火墙是否放行 4433套件能打开但同步失败
优先检查：
text
套件密钥是否与云端服务一致
服务 URL 地址是否使用 https://im-login-server.example.com
云端服务证书是否可信
套件是否以 root 身份运行permission denied
说明套件没有足够权限执行 DSM 用户和群组命令。重新执行：
bash
sh /var/packages/im-synology-login-plugin/target/var/grant-root.sh然后在套件中心重启套件。