128 lines
4.0 KiB
Markdown
128 lines
4.0 KiB
Markdown
# CLAUDE.md — LLDAP 用户目录服务
|
||
|
||
## 项目概述
|
||
|
||
ldap-ai 是基于 [LLDAP](https://github.com/lldap/lldap) 的轻量级 LDAP 用户目录服务，域名为内部服务（不对外暴露）。为 OA 统一门户、工单系统、资产管理系统提供统一的 LDAP 用户认证。`dc=tlyq,dc=ai`。
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 用途 | 统一用户目录（LDAP 认证） |
|
||
| 服务器 | txjp（IP: 43.133.38.210） |
|
||
| 代码路径 | `/root/docker/ldap-ai/` |
|
||
| 容器名 | `lldap` |
|
||
| 镜像 | `lldap/lldap:stable-alpine` |
|
||
| LDAP Base DN | `dc=tlyq,dc=ai` |
|
||
| 本地端口 | 6178（Web UI）/ 3890（LDAP） |
|
||
| 默认管理员 | `admin` / `admin123` |
|
||
| 数据目录 | `data/lldap/`（宿主机挂载） |
|
||
|
||
---
|
||
|
||
## 关键文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `docker-compose.yml` | 生产部署（共用 webnet，不暴露端口） |
|
||
| `docker-compose.local.yml` | 本地开发（暴露 6178 + 3890 端口） |
|
||
| `.env` | 环境变量（JWT secret、admin 密码、LDAP 端口等） |
|
||
| `.env.example` | 环境变量模板 |
|
||
| `data/lldap/` | LLDAP 持久化数据（SQLite 用户数据库） |
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `LLDAP_JWT_SECRET` | LLDAP JWT 签名密钥 |
|
||
| `LLDAP_ADMIN_PASSWORD` | LLDAP admin 用户的 LDAP 密码（也是 Web UI 登录密码） |
|
||
| `LLDAP_LDAP_USER_PASS` | LDAP 只读用户的绑定密码（供应用 bind 用） |
|
||
| `LLDAP_LDAP_BASE_DN` | LDAP Base DN（`dc=tlyq,dc=ai`） |
|
||
| `LLDAP_HTTP_PORT` | Web UI 端口（容器内 17170） |
|
||
| `LLDAP_LDAP_PORT` | LDAP 端口（容器内 3890） |
|
||
| `LLDAP_DATABASE_PATH` | SQLite 数据库路径 |
|
||
|
||
---
|
||
|
||
## Docker 部署
|
||
|
||
```
|
||
txjp 服务器
|
||
├── lldap（容器） ← LLDAP stable-alpine，暴露 :3890
|
||
├── oa-ai / assets-ai / issue-ai ← 各站点直连 lldap:3890 做 LDAP 认证
|
||
└── webnet（external） ← 共享网络
|
||
```
|
||
|
||
**启动**：
|
||
```bash
|
||
# 本地开发
|
||
cd ldap-ai
|
||
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d
|
||
|
||
# 云服务器
|
||
ssh txjp "cd /root/docker/ldap-ai && docker compose up -d"
|
||
```
|
||
|
||
**Web UI**：`http://localhost:6178`（admin / admin123）
|
||
|
||
---
|
||
|
||
## 认证机制
|
||
|
||
各站点（OA/assets/issue）直连 LLDAP 进行 LDAP bind 认证：
|
||
|
||
1. **ldapAuth(username, password)**：用户 DN bind 验证 → 成功返回用户信息
|
||
2. **ldapUserExists(username)**：用 admin 凭据搜索用户是否存在（Q1 安全需求：已删除用户需强制退出）
|
||
3. **LDAP 密码管理**：OA 通过 `docker exec lldap lldap_set_password` 修改密码
|
||
|
||
---
|
||
|
||
## 开发规范
|
||
|
||
- **新增用户**：通过 OA 用户管理页面创建，底层调用 LLDAP API
|
||
- **删除用户**：OA 标记 LLDAP 用户为 inactive，各站点 `ldapUserExists()` 检测到后清除 cookie 踢出
|
||
- **改密码**：OA 调用 `docker exec lldap` 执行 `lldap_set_password` 脚本
|
||
- **LLDAP 故障容错**：`ldapUserExists()` 在 LLDAP 不可达时返回 `true`（放行），不阻断正常登录
|
||
- **admin 密码**：`LLDAP_ADMIN_PASSWORD` 是唯一来源，各站点通过运行时 `docker exec lldap printenv` 动态获取，不写入各站点 `.env`
|
||
|
||
---
|
||
|
||
## Git Tag 规范
|
||
|
||
使用日期版本号 `vYYYY.MM.DD`（如 `v2026.05.18`）。提交后打 tag 再推送：
|
||
|
||
```bash
|
||
git tag v$(date +%Y.%m.%d) && git push origin main && git push origin v$(date +%Y.%m.%d)
|
||
```
|
||
|
||
同一天多次提交只打一个 tag。详见根目录 `CLAUDE.md`。
|
||
|
||
---
|
||
|
||
## 服务器操作
|
||
|
||
```bash
|
||
# 重启
|
||
ssh txjp "cd /root/docker/ldap-ai && docker compose restart"
|
||
|
||
# 重建（配置变更后）
|
||
ssh txjp "cd /root/docker/ldap-ai && docker compose down && docker compose up -d"
|
||
|
||
# 安装 sqlite3（LLDAP 容器内，用于 OA 用户管理）
|
||
ssh txjp "docker exec lldap apk add --no-cache sqlite"
|
||
|
||
# 查看日志
|
||
ssh txjp "docker logs lldap"
|
||
```
|
||
|
||
### 容器重建后
|
||
|
||
LLDAP 容器重建后，OA 容器需能访问 `sqlite3`（用于查询跨站点用户数据）。每次容器重建后需重新安装：
|
||
```bash
|
||
docker exec lldap apk add --no-cache sqlite
|
||
```
|