# 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
```