WeKnora部署教程：WeKnora与企业AD/LDAP集成，实现SSO单点登录

WeKnora部署教程：WeKnora与企业AD/LDAP集成，实现SSO单点登录

想象一下这个场景：公司新来的同事需要快速了解一个复杂的项目，他不用去翻找堆积如山的文档，也不用打扰正在忙碌的同事，只需要打开一个网页，输入问题，就能立刻得到基于最新项目文档的准确答案。

这就是WeKnora带来的价值。它是一个基于大模型的智能知识库问答系统，能让你把任何文本变成AI的“即时知识库”，然后进行精准问答。

但今天我们要聊的，不仅仅是WeKnora的基础功能。对于企业用户来说，还有一个更关键的需求：如何让公司成百上千的员工，都能安全、便捷地使用这个系统？难道要为每个人单独创建账号和密码吗？这显然不现实。

答案就是与企业现有的身份认证系统（如Active Directory或LDAP）集成，实现单点登录（SSO）。这意味着员工可以用自己公司的统一账号密码直接登录WeKnora，无需记忆另一套凭证，管理员也无需手动管理用户账号。

本文将手把手带你完成WeKnora与企业AD/LDAP的集成部署，实现SSO单点登录。

1. 准备工作与环境要求

在开始集成之前，我们需要确保环境准备就绪。这个过程并不复杂，但需要一些基础的网络和系统知识。

1.1 系统与网络要求

首先，确认你的部署环境满足以下基本要求：

• 操作系统：支持主流Linux发行版（Ubuntu 20.04+、CentOS 7+等）或Windows Server
• Docker环境：已安装Docker和Docker Compose
• 网络访问：
  • 部署服务器能够访问企业AD/LDAP服务器
  • 用户能够通过浏览器访问WeKnora服务
• 权限要求：对AD/LDAP服务器有查询权限的只读账号

1.2 获取必要的AD/LDAP信息

这是最关键的一步。你需要从公司的IT部门或系统管理员那里获取以下信息：

# 你需要收集的AD/LDAP配置信息示例 ldap_config: server_url: "ldap://ad.company.com:389" # LDAP服务器地址和端口 bind_dn: "cn=readonly,ou=service,dc=company,dc=com" # 绑定账号 bind_password: "your_password_here" # 绑定密码 user_search_base: "ou=users,dc=company,dc=com" # 用户搜索基础DN user_search_filter: "(sAMAccountName={0})" # 用户搜索过滤器 group_search_base: "ou=groups,dc=company,dc=com" # 组搜索基础DN（可选）

如果你不确定这些信息是什么，没关系。可以这样向IT同事询问：“我们需要连接公司AD/LDAP实现单点登录，请提供LDAP服务器地址、一个只读查询账号，以及用户账号所在的组织单元路径。”

1.3 下载WeKnora部署文件

WeKnora提供了完整的Docker部署方案，我们需要先获取部署文件：

# 创建项目目录 mkdir weknora-ldap && cd weknora-ldap # 下载部署配置文件（这里以示例URL为例，实际请参考官方文档） wget https://example.com/weknora-docker-compose.yml wget https://example.com/weknora-ldap-config.env

如果你无法直接下载，也可以手动创建这些文件。接下来我们会详细讲解每个文件的内容。

2. 配置WeKnora与AD/LDAP集成

现在进入核心配置环节。WeKnora使用Keycloak作为身份认证中间件，通过Keycloak实现与AD/LDAP的集成。

2.1 理解集成架构

先简单了解一下整个集成的架构，这样配置时会更加清晰：

企业用户浏览器 → WeKnora Web界面 → Keycloak认证 → AD/LDAP服务器 ↑ ↑ ↑ 单点登录 重定向到 验证用户凭证 认证页面 并同步用户信息

简单来说，当用户访问WeKnora时，会被重定向到Keycloak登录页面，用户输入AD账号密码，Keycloak去AD服务器验证，验证通过后返回WeKnora。

2.2 配置Keycloak连接AD/LDAP

这是最关键的一步。我们需要修改Keycloak的配置文件，让它能够连接你的企业AD/LDAP。

首先，创建或修改keycloak-ldap-config.cli文件：

# 连接LDAP服务器的基本配置 /subsystem=elytron/dir-context=companyLDAP:add( url="ldap://ad.company.com:389", principal="cn=readonly,ou=service,dc=company,dc=com", credential="your_password_here" ) # 配置用户映射 /subsystem=keycloak-server/spi=userFederation/provider=ldap/:add(enabled=true) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.vendor, value=ad ) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.usernameLDAPAttribute, value=sAMAccountName ) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.rdnLDAPAttribute, value=cn ) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.uuidLDAPAttribute, value=objectGUID ) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.userObjectClasses, value=person,organizationalPerson,user ) # 配置用户搜索 /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.searchScope, value=1 ) /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.usersDn, value=ou=users,dc=company,dc=com )

重要提示：上面的配置示例中，你需要替换以下内容：

• ad.company.com:389→ 你的AD服务器地址和端口
• cn=readonly,ou=service,dc=company,dc=com→ 你的只读绑定账号
• your_password_here→ 绑定账号的密码
• ou=users,dc=company,dc=com→ 你的用户组织单元路径

2.3 配置Docker Compose文件

接下来，我们需要创建一个Docker Compose文件，同时启动WeKnora和Keycloak服务。

创建docker-compose.yml文件：

version: '3.8' services: # Keycloak身份认证服务 keycloak: image: quay.io/keycloak/keycloak:latest container_name: weknora-keycloak command: ["start-dev", "--import-realm"] environment: KEYCLOAK_ADMIN: admin KEYCLOAK_ADMIN_PASSWORD: admin_password KC_FEATURES: scripts volumes: - ./keycloak-ldap-config.cli:/opt/keycloak/conf/cli-scripts/ldap-config.cli - ./weknora-realm.json:/opt/keycloak/data/import/weknora-realm.json ports: - "8080:8080" networks: - weknora-network healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"] interval: 30s timeout: 10s retries: 3 # WeKnora主服务 weknora: image: weknora/weknora:latest container_name: weknora-app environment: - AUTH_TYPE=oidc - OIDC_CLIENT_ID=weknora-client - OIDC_CLIENT_SECRET=your_client_secret_here - OIDC_ISSUER=http://keycloak:8080/realms/weknora - OIDC_AUTHORIZATION_ENDPOINT=http://keycloak:8080/realms/weknora/protocol/openid-connect/auth - OIDC_TOKEN_ENDPOINT=http://keycloak:8080/realms/weknora/protocol/openid-connect/token - OIDC_USERINFO_ENDPOINT=http://keycloak:8080/realms/weknora/protocol/openid-connect/userinfo - OIDC_END_SESSION_ENDPOINT=http://keycloak:8080/realms/weknora/protocol/openid-connect/logout ports: - "3000:3000" depends_on: keycloak: condition: service_healthy networks: - weknora-network networks: weknora-network: driver: bridge

2.4 创建Keycloak Realm配置

我们还需要创建一个Realm配置文件，定义WeKnora的客户端和用户角色。

创建weknora-realm.json文件：

{ "realm": "weknora", "enabled": true, "users": [], "clients": [ { "clientId": "weknora-client", "enabled": true, "publicClient": false, "secret": "your_client_secret_here", "redirectUris": [ "http://localhost:3000/*", "http://your-weknora-domain.com/*" ], "webOrigins": ["*"], "protocol": "openid-connect", "attributes": { "backchannel.logout.session.required": "true", "backchannel.logout.revoke.offline.tokens": "false" } } ], "roles": { "realm": [ { "name": "weknora-user", "description": "普通用户角色，可以提问和查看答案" }, { "name": "weknora-admin", "description": "管理员角色，可以管理知识库和用户" } ] } }

3. 部署与启动服务

配置完成后，现在可以启动服务了。这个过程相对简单，但需要按顺序进行。

3.1 启动Keycloak并配置LDAP

首先启动Keycloak服务，并应用我们的LDAP配置：

# 1. 启动Keycloak（单独启动，先配置LDAP） docker-compose up -d keycloak # 2. 等待Keycloak完全启动（大约30-60秒） sleep 60 # 3. 执行LDAP配置脚本 docker exec weknora-keycloak /opt/keycloak/bin/kc.sh config --file=/opt/keycloak/conf/cli-scripts/ldap-config.cli # 4. 重启Keycloak使配置生效 docker-compose restart keycloak

3.2 启动完整的WeKnora服务

Keycloak配置完成后，启动完整的服务栈：

# 启动所有服务 docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志，确认服务正常运行 docker-compose logs -f weknora

如果一切正常，你应该能看到类似下面的输出：

weknora-app | Server is running on port 3000 weknora-app | OIDC authentication configured successfully

3.3 验证服务可访问性

现在验证服务是否正常运行：

# 检查Keycloak是否可访问 curl -f http://localhost:8080/realms/weknora/.well-known/openid-configuration # 检查WeKnora是否可访问 curl -f http://localhost:3000/health

如果返回正常的JSON响应，说明服务已经启动成功。

4. 测试单点登录功能

服务部署完成后，最重要的环节是测试。我们需要确保单点登录功能正常工作。

4.1 首次访问测试

打开浏览器，访问WeKnora服务地址（通常是http://你的服务器IP:3000）。

你应该会看到以下流程：

1. 重定向到登录页面：访问WeKnora时，会自动跳转到Keycloak登录页面
2. 输入AD账号密码：在Keycloak页面输入你的企业AD账号和密码
3. 授权确认：首次登录可能需要确认授权（允许WeKnora访问你的基本信息）
4. 跳转回WeKnora：认证成功后，自动跳转回WeKnora主界面

4.2 常见问题排查

如果登录过程中遇到问题，可以按照以下步骤排查：

# 1. 检查Keycloak日志 docker-compose logs keycloak | grep -i "ldap\|error\|fail" # 2. 检查WeKnora日志 docker-compose logs weknora | grep -i "auth\|oidc\|error" # 3. 测试LDAP连接（在服务器上执行） ldapsearch -x -H ldap://ad.company.com:389 \ -D "cn=readonly,ou=service,dc=company,dc=com" \ -w "your_password_here" \ -b "ou=users,dc=company,dc=com" \ "(sAMAccountName=你的账号)" \ dn # 4. 检查网络连通性 telnet ad.company.com 389

4.3 多用户测试

单点登录的核心价值是支持多用户。你可以邀请几位同事一起测试：

1. 不同部门的同事：测试是否所有部门的AD账号都能登录
2. 不同权限的账号：测试普通员工和管理员账号的登录情况
3. 并发登录测试：多个用户同时登录，测试系统稳定性

5. 高级配置与优化

基础集成完成后，你可能还需要一些高级配置来满足特定需求。

5.1 配置用户角色同步

默认情况下，WeKnora只同步用户基本信息。如果你需要根据AD中的组信息分配WeKnora角色，可以这样配置：

在keycloak-ldap-config.cli中添加组映射配置：

# 配置组映射 /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.memberOfLDAPAttribute, value=memberOf ) # 配置组搜索 /subsystem=keycloak-server/spi=userFederation/provider=ldap/:write-attribute( name=properties.groupSearchBase, value=ou=groups,dc=company,dc=com ) # 配置角色映射规则 /subsystem=keycloak-server/spi=role-mappers/provider=ldap-role-mapper/:add(enabled=true) /subsystem=keycloak-server/spi=role-mappers/provider=ldap-role-mapper/:write-attribute( name=properties.groups.ldap.filter, value=(&(objectClass=group)(member={1})) )

5.2 配置HTTPS安全访问

生产环境强烈建议使用HTTPS。你需要配置SSL证书：

# 修改docker-compose.yml中的Keycloak服务配置 keycloak: # ... 其他配置保持不变 environment: # 添加HTTPS配置 KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/server.crt KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/server.key KC_HOSTNAME: sso.your-company.com volumes: # 挂载SSL证书 - ./ssl/server.crt:/opt/keycloak/conf/server.crt - ./ssl/server.key:/opt/keycloak/conf/server.key

5.3 配置会话管理与单点登出

单点登录的一个重要特性是单点登出。配置正确的登出重定向：

# 在WeKnora环境变量中添加登出配置 weknora: environment: # ... 其他OIDC配置 - OIDC_END_SESSION_ENDPOINT=http://keycloak:8080/realms/weknora/protocol/openid-connect/logout - OIDC_POST_LOGOUT_REDIRECT_URI=http://your-weknora-domain.com

6. 实际应用场景与效果

完成集成后，让我们看看在实际企业环境中，这个方案能带来什么价值。

6.1 场景一：新员工快速上手

传统方式：新员工需要向多个同事询问，查阅大量文档，花费数天时间才能了解项目全貌。

使用WeKnora后：新员工登录系统，输入问题：“本项目的主要技术架构是什么？”立即获得基于最新技术文档的准确答案。整个过程不到5分钟。

6.2 场景二：跨部门协作

传统方式：市场部需要了解产品的技术细节，需要预约技术部的同事开会，或者等待邮件回复。

使用WeKnora后：市场部同事直接登录系统，提问：“产品支持的最大并发用户数是多少？”系统基于技术规格文档给出准确数字，无需打扰技术人员。

6.3 场景三：客户支持

传统方式：客服人员需要翻阅厚厚的产品手册，或者转接给技术支持。

使用WeKnora后：客服登录系统，输入客户问题：“如何重置设备到出厂设置？”系统基于用户手册给出步骤清晰的答案，提升客服效率和客户满意度。

6.4 管理效益分析

从管理角度看，这个集成方案带来了多重价值：

1. 统一身份管理：无需在WeKnora中单独管理用户账号，所有账号来自企业AD
2. 安全可控：员工离职后，AD账号被禁用，自动失去WeKnora访问权限
3. 使用便捷：员工无需记忆额外密码，提升使用意愿
4. 审计合规：所有登录行为可以通过AD日志进行审计

7. 维护与监控建议

系统上线后，适当的维护和监控能确保长期稳定运行。

7.1 日常监控检查

建议设置以下监控项：

#!/bin/bash # 每日健康检查脚本示例 # 1. 检查服务状态 docker-compose ps | grep -v "Up" # 2. 检查日志错误 docker-compose logs --tail=100 weknora | grep -i "error\|exception" docker-compose logs --tail=100 keycloak | grep -i "error\|exception" # 3. 测试登录流程（模拟用户登录） curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 # 4. 检查LDAP连接 # 可以定期测试LDAP绑定是否正常

7.2 定期备份策略

重要的配置和数据需要定期备份：

#!/bin/bash # 备份脚本示例 BACKUP_DIR="/backup/weknora-$(date +%Y%m%d)" mkdir -p $BACKUP_DIR # 备份Docker Compose配置 cp docker-compose.yml $BACKUP_DIR/ cp *.env $BACKUP_DIR/ cp *.cli $BACKUP_DIR/ cp *.json $BACKUP_DIR/ # 备份Keycloak数据库（如果使用外部数据库） # docker exec weknora-keycloak pg_dump -U keycloak > $BACKUP_DIR/keycloak_db.sql # 压缩备份文件 tar -czf $BACKUP_DIR.tar.gz $BACKUP_DIR

7.3 故障处理指南

遇到问题时，可以按以下流程排查：

1. 用户无法登录

   • 检查AD/LDAP服务器是否可达
   • 检查绑定账号密码是否过期
   • 检查用户账号是否被禁用

2. 登录后无法访问WeKnora

   • 检查Keycloak与WeKnora的网络连通性
   • 检查OIDC客户端配置是否正确
   • 查看WeKnora日志中的认证错误

3. 性能问题

   • 检查服务器资源使用情况（CPU、内存）
   • 检查网络延迟
   • 考虑增加缓存或优化查询

8. 总结

通过本文的步骤，我们完成了WeKnora与企业AD/LDAP的集成，实现了单点登录功能。回顾整个过程，有几个关键点值得总结：

8.1 核心价值实现

这次集成的核心价值在于无缝衔接：将先进的AI知识问答能力无缝融入企业现有的IT基础设施。员工不需要学习新系统，不需要记忆新密码，用最熟悉的方式获得最智能的帮助。

8.2 技术要点回顾

整个集成方案的技术栈清晰合理：

• WeKnora：提供核心的AI问答能力
• Keycloak：作为认证中间件，桥接WeKnora和AD/LDAP
• Docker：简化部署和运维
• OIDC协议：实现标准的单点登录流程

每个组件都扮演着明确的角色，共同构建了一个稳定可靠的企业级解决方案。

8.3 实际部署建议

根据我们的实施经验，给计划部署的企业几点建议：

1. 分阶段实施：先在测试环境验证，然后小范围试点，最后全面推广
2. 充分沟通：提前与IT部门沟通，获取准确的AD/LDAP配置信息
3. 用户培训：虽然系统易用，但适当的培训能更快发挥价值
4. 持续优化：根据用户反馈，不断优化知识库内容和问答质量

8.4 未来扩展方向

这个基础集成方案还有很大的扩展空间：

• 多因素认证：在Keycloak中配置短信、邮件或硬件令牌认证
• 细粒度权限：根据AD组信息控制不同的知识库访问权限
• 使用分析：集成分析工具，了解哪些知识被频繁查询
• 移动端支持：优化移动端登录和使用体验

企业知识管理正在从“文档存储”向“智能问答”演进。WeKnora与AD/LDAP的集成，让这个演进过程更加平滑自然。员工用最少的改变，获得最大的效率提升。

现在，你的企业也拥有了一个7x24小时在线的智能知识助手，它熟悉公司的每一个产品、每一个流程、每一个最佳实践。当员工有疑问时，不再需要“找对人问对问题”，只需要“问对系统”，就能获得准确答案。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。