统一用户管理实操指南：零门槛3步搭建可直接用的系统

准备工作

先安装Docker及Docker Compose，执行以下命令（仅支持Ubuntu 20.04+，其他系统可替换对应安装命令）：

安装命令：sudo apt update && sudo apt install docker.io docker-compose -y

验证安装：执行docker --version和docker-compose --version，出现版本号即成功。

第一步：拉取统一用户管理核心镜像

本次实操使用开源标准的Keycloak作为统一用户管理服务，执行拉取命令：

镜像拉取命令：docker pull quay.io/keycloak/keycloak:latest

第二步：编写启动配置文件

新建名为docker-compose.yml的文件，复制以下完整内容（路径不要含中文，直接放在桌面或任意英文目录）：

``` version: '3.8' services: keycloak: image: quay.io/keycloak/keycloak:latest environment: KEYCLOAK_ADMIN: admin KEYCLOAK_ADMIN_PASSWORD: admin123 ports: - "8080:8080" command: start-dev ```

重点注意：文件名必须完全是docker-compose.yml，不可改名或改后缀，否则启动失败。

第三步：启动服务并初始化

1. 执行启动命令，后台运行服务：

启动命令：docker-compose up -d

2. 等待30秒，服务启动完成后，打开浏览器输入http://localhost:8080/admin

3. 初始登录账号：admin，密码：admin123，首次登录必须修改密码：点击右上角头像→Manage Account→Security→Password，输入新密码后保存。

核心操作：对接第一个业务系统

统一用户管理的核心是关联业务系统，步骤如下：

• 1. 左侧菜单点击Clients→Create，Client ID输入your-app（自定义，比如我的博客），点击Save。
• 2. Settings页：Root URL填业务系统地址（比如http://localhost:3000），Valid Redirect URIs填http://localhost:3000/，点击Save。
• 3. 切换到Credentials页，复制Client Secret（后续业务系统对接必须用，务必妥善保存，不要泄露）。

验证对接效果

1. 在Keycloak中添加测试用户：Users→Add User，输入用户名test，点击Save；再点击Credentials→Set Password，输入123456，取消Temporary（临时密码），点击Save。

2. 新建业务系统测试代码，复制以下内容到app.js：

``` const express = require('express'); const session = require('express-session'); const Keycloak = require('keycloak-connect'); const app = express(); const memoryStore = new session.MemoryStore(); app.use(session({ secret: 'your-session-secret', resave: false, saveUninitialized: true, store: memoryStore })); const keycloak = new Keycloak({ store: memoryStore }, { clientId: 'your-app', bearerOnly: false, serverUrl: 'http://localhost:8080/', realm: 'master', clientSecret: '刚才复制的Client Secret' }); app.use(keycloak.middleware()); app.get('/', keycloak.protect(), (req, res) => { res.send(`登录成功！当前用户：${req.kauth.grant.access_token.content.preferred_username}`); }); app.listen(3000, () => console.log('业务系统运行在http://localhost:3000')); ```

3. 启动业务系统：先装依赖，执行npm install express express-session keycloak-connect；再执行node app.js。

4. 打开浏览器输入http://localhost:3000，会自动跳转到Keycloak登录页，输入test/123456，成功后显示登录信息，说明对接完成。

日常维护操作

• 停止服务：docker-compose down
• 重启服务：docker-compose restart
• 查看运行日志：docker-compose logs -f keycloak