IM Synology Login Server 企微群晖登录服务

IM Synology Login Server 是企微群晖登录的云端服务。正式环境建议使用 Docker 镜像部署，前面由 Nginx 和 HTTPS 反向代理，前端管理后台已经打进镜像，不需要单独部署前端。

这篇文档只讲云端服务。群晖 NAS 上的 SPK 套件请看 IM Synology Login Plugin 套件文档。

部署完成后，它会提供三类能力：

给管理员使用的 Web 管理后台。
给 DSM 使用的 OpenID Connect Provider。
给群晖套件使用的任务接口和通讯录同步接口。

运行环境

服务器需要准备：

text

Docker
Docker Compose
Nginx
MySQL 8.0+
HTTPS 证书

推荐域名：

text

im-login-server.example.com A 记录 -> 云端服务器公网 IP

防火墙放行：

text

80/tcp
443/tcp

服务容器默认监听宿主机本地端口 58001。外网不要直接暴露这个端口，通过 Nginx 反向代理访问即可。

部署前先确认三件事：

项目	要求
云端域名	已解析到服务器，例如 `im-login-server.example.com`。
HTTPS	证书已签发或准备签发，正式环境不要用 HTTP。
MySQL	已准备 MySQL 8.0+，安装向导会连接这个库。

源码结构

text

im-synology-login-server/
├── backend/                         Spring Boot 后端
├── frontend/                        React + Vite 管理后台
├── backend/migrations/001_init.sql  MySQL 初始化脚本
├── deployments/                     Docker Compose、Nginx 和安装脚本
├── docs/                            项目内部部署和接口文档
└── scripts/                         镜像与部署包打包脚本

常用本地验证：

bash

cd backend
mvn test

bash

cd frontend
npm install
npm run build

根目录构建镜像：

bash

docker build --platform linux/amd64 -t im-synology-login-server:latest .

生成部署包

在项目根目录执行：

bash

./scripts/package-image-local.sh
./scripts/package-deployment-local.sh

也可以一步完成：

bash

BUILD_IMAGE=true ./scripts/package-deployment-local.sh

生成文件：

text

release/im-synology-login-server_latest_amd64.tar
release/im-synology-login-server-deploy.tar.gz

如果团队已经接入 Jenkins，建议由 Jenkins 完成镜像构建、导出镜像 tar、上传服务器和远程启动容器。这样可以保证生产环境只接收镜像和部署包，不依赖开发机状态。

上传并安装

上传部署包：

bash

scp release/im-synology-login-server-deploy.tar.gz root@服务器IP:/opt/docker/

服务器执行：

bash

cd /opt/docker
tar -xzf im-synology-login-server-deploy.tar.gz
cd im-synology-login-server
bash deployments/install-server.sh --domain im-login-server.example.com --host-port 58001

脚本会完成：

text

生成 .env
创建 data/ 持久化目录
渲染 deployments/nginx.generated.conf
docker load 导入镜像
docker compose up -d 启动容器

data/ 目录用于保存初始化向导生成的 bootstrap.json。不要把它放到临时目录，也不要在升级时删除。

查看服务日志：

bash

docker compose logs -f im-login-server

本机健康检查：

bash

curl http://127.0.0.1:58001/healthz

如果只想生成初始化文件，不启动容器：

bash

bash deployments/install-server.sh --domain im-login-server.example.com --host-port 58001 --skip-docker

如果希望脚本同时复制 Nginx 配置并重载：

bash

bash deployments/install-server.sh --domain im-login-server.example.com --host-port 58001 --install-nginx

Nginx 与 HTTPS

安装脚本会生成：

text

deployments/nginx.generated.conf

检查其中核心配置：

text

server_name im-login-server.example.com;
proxy_pass http://127.0.0.1:58001;

当前脚本生成的是 HTTP 反向代理基线配置。生产环境需要在同一个 server_name 上配置 HTTPS 证书，或接入你现有的证书自动签发流程，再反代到 127.0.0.1:58001。

复制到 Nginx：

bash

sudo cp deployments/nginx.generated.conf /etc/nginx/conf.d/im-login-server.example.com.conf
sudo nginx -t
sudo systemctl reload nginx

签发并配置 HTTPS 后验证：

bash

curl https://im-login-server.example.com/healthz
curl https://im-login-server.example.com/.well-known/openid-configuration

企业微信可信域名、扫码登录和 DSM OIDC 都依赖公网 HTTPS，正式环境不要用 HTTP。

初始化安装

浏览器打开：

text

https://im-login-server.example.com/admin

首次启动没有 bootstrap.json 时会进入安装向导。按页面填写：

text

MySQL 地址
MySQL 端口
数据库名
数据库用户名
数据库密码
安装方式：全新安装 / 已有 MySQL 数据库
登录方式：内置登录 / 外部 SSO
公网访问地址 / OIDC Issuer：https://im-login-server.example.com
管理员用户名和密码

安装完成后重启容器：

bash

docker compose restart im-login-server

重启后再次打开：

text

https://im-login-server.example.com/admin

新增服务配置

进入管理后台：

text

IM 配置服务 -> 新增服务

一条服务对应一条“企业微信应用 -> 群晖 NAS”的登录和同步链路。

服务列表

服务列表用于维护多套企业微信应用或多台 NAS。新部署时先点“新增服务”，已经有服务时从这里进入详情页修改配置。

服务详情页需要配置：

text

企业微信 CorpID
企业微信 AgentID
企业微信应用 Secret
Well-known URL
OIDC Client ID
OIDC Client Secret
DSM 访问地址
重定向 URI
套件密钥

服务详情

保存服务后，页面会生成 OIDC Client ID 和 OIDC Client Secret。这两个值后面要原样复制到 DSM 的 OpenID Connect SSO 配置里。

几个容易填错的字段：

字段	怎么填
`Well-known URL`	使用云端公网地址，例如 `https://im-login-server.example.com/.well-known/openid-configuration`。
`OIDC Client ID` / `OIDC Client Secret`	云端服务生成并保存后，DSM OIDC 里填同一组值。
`DSM 访问地址`	用户实际访问 DSM / Drive 的外网地址，例如 `https://nas.example.com:4433`。
`重定向 URI`	必须与 DSM OIDC 页面要求一致，通常也是 DSM 外网入口的 `scheme + host + port`。
`套件密钥`	从群晖套件页面复制，不能在云端随便编一个。

企业微信配置

企业微信后台需要配置这些地址：

text

工作台首页地址：
https://im-login-server.example.com/dsm?client_id=<后台生成的 oidc.client_id>

网页授权可信域名：
im-login-server.example.com

OAuth 回调地址：
https://im-login-server.example.com/oauth/wecom/callback

通讯录回调 URL：
https://im-login-server.example.com/api/wecom/callback

工作台首页地址建议直接复制“集成自检”页面输出，不要自己手拼。用户以后在企业微信工作台里点击应用，就会从这里进入 DSM 登录流程。

企业微信工作台入口

配置完成后，企业微信工作台里应该能看到应用入口。入口名称和图标在企业微信后台配置，入口地址使用云端服务给出的 /dsm?client_id=...。

如果企业微信要求域名校验文件，进入管理后台：

text

集成自检 -> 企业微信域名校验文件 -> 上传 WW_verify_*.txt

上传后按页面给出的验证地址去企业微信后台完成校验。

集成自检

集成自检页会把“应该填到企业微信后台的地址”和“应该填到 DSM 的 OIDC 参数”集中列出来。部署时建议从这里复制，避免手工拼错路径或参数。

通讯录同步的 Token 和 EncodingAESKey 要在企业微信后台和云端服务后台保持完全一致。Token 是你自己设置的一串随机字符；EncodingAESKey 用企业微信后台的随机生成按钮生成。

DSM OpenID Connect SSO 配置

DSM 控制面板中进入：

text

域/LDAP -> SSO 客户端 -> OpenID Connect SSO 设置

填写：

text

配置文件：OIDC
账户类型：域/LDAP/本地
名称：IM Synology Login
Well-known URL：https://im-login-server.example.com/.well-known/openid-configuration
应用程序 ID：后台服务生成的 oidc.client_id
应用程序密钥：后台服务生成的 oidc.client_secret
重定向 URI：https://nas.example.com:4433
授权范围：openid profile email
用户名声明：preferred_username

DSM OIDC 配置

DSM 这里的“应用程序 ID / 密钥”必须和云端服务里的 oidc.client_id / oidc.client_secret 一致。只要其中一个值不一致，DSM 就会停在 OIDC 登录或回调错误页。

重定向 URI 填用户实际访问 DSM 的外网入口，不要填云端服务地址。例如用户通过 https://nas.example.com:4433 打开 DSM，这里也填这个地址。

关联群晖套件

云端服务不能自己修改 NAS 用户。真正执行用户和群组命令的是 NAS 上的套件。

套件安装完成后，在套件页面复制“套件密钥”，回到云端服务详情页填写：

text

群晖套件 -> 套件密钥

然后在云端执行：

text

集成自检 -> 测试群晖套件

如果这里失败，优先检查：

text

套件页面服务 URL 是否是 https://im-login-server.example.com
套件密钥是否和云端完全一致
套件是否已保存配置并启动自动拉取

通讯录同步

进入管理后台：

text

通讯录同步

操作顺序：

点击“刷新通讯录”。
左侧勾选需要同步到群晖的企业微信部门。
点击“确认同步范围”。
确认右侧人员列表和状态。
安装并配置群晖套件后，执行“批量同步”。

通讯录同步

第一次同步建议先在套件里打开“只演练”。确认任务、日志和目标用户都符合预期后，再关闭只演练并真正写入 DSM。

登录链路验证

配置完成后，从企业微信工作台打开应用，企微客户端会先进入 DSM 同源自动 SSO 页面，再跳转企业微信授权。

企业微信进入 DSM 过渡页

如果在普通浏览器里访问登录入口，会出现企业微信扫码登录。

浏览器扫码登录企业微信

手机企业微信扫码后会出现登录确认页。

确认后应回到 DSM。

登录完成进入 DSM

完整链路可以按下面检查：

text

企业微信工作台
-> /dsm?client_id=<后台生成的 oidc.client_id>
-> DSM 同源 auto-sso.html
-> DSM OIDC
-> 企业微信授权或扫码登录
-> 群晖 DSM / Drive

验证标准

服务器本机：

bash

curl http://127.0.0.1:58001/healthz

公网：

bash

curl https://im-login-server.example.com/healthz
curl https://im-login-server.example.com/.well-known/openid-configuration
curl https://im-login-server.example.com/oauth/jwks

后台自检：

text

集成自检 -> 测试企业微信
集成自检 -> 测试群晖套件
通讯录同步 -> 刷新通讯录
通讯录同步 -> 批量同步

登录验收：

text

企业微信工作台能看到应用入口
普通浏览器能进入企业微信扫码登录
手机企业微信扫码后能确认登录
最终能回到 DSM / Drive

常见问题

DSM 无法完成 OIDC 登录

优先检查：

text

oidc.issuer 是否等于公网 HTTPS 地址
DSM Well-known URL 是否能访问
DSM 应用程序 ID / 密钥是否等于后台生成值
重定向 URI 是否与 DSM 外网入口完全一致

企业微信回调保存失败

优先检查：

text

可信域名是否只填域名，不带 https:// 和路径
WW_verify_*.txt 是否已上传到云端服务
回调 Token 和 EncodingAESKey 是否与后台配置完全一致

同步任务不执行

优先检查：

text

群晖套件是否已启动
套件密钥是否已复制到云端服务
套件页面“测试云端连接”是否成功
套件是否已获得 root 权限

IM Synology Login Server 企微群晖登录服务 ​

运行环境 ​

源码结构 ​

生成部署包 ​

上传并安装 ​

Nginx 与 HTTPS ​

初始化安装 ​

新增服务配置 ​

企业微信配置 ​

DSM OpenID Connect SSO 配置 ​

关联群晖套件 ​

通讯录同步 ​

登录链路验证 ​

验证标准 ​

常见问题 ​

DSM 无法完成 OIDC 登录 ​

企业微信回调保存失败 ​

同步任务不执行 ​

IM Synology Login Server 企微群晖登录服务

运行环境

源码结构

生成部署包

上传并安装

Nginx 与 HTTPS

初始化安装

新增服务配置

企业微信配置

DSM OpenID Connect SSO 配置

关联群晖套件

通讯录同步

登录链路验证

验证标准

常见问题

DSM 无法完成 OIDC 登录

企业微信回调保存失败

同步任务不执行