# CZXK

**Repository Path**: blib/CZXK

## Basic Information

- **Project Name**: CZXK
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-02
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业知识库

## 常州西控平台一期

当前基座已扩展供应商资料、项目进展、业务总览和业务角色权限。交付状态、技术验收与生产访问方式见[一期交付验收与部署说明](../../一期交付验收与部署说明.md)；详细功能清单见[一期开发计划](../../一期开发计划.md)。

新增业务接口统一为 `/api/v1/biz/*`，业务表沿用实际 Flyway schema `enterprise_kb`。供应商 AI 抽取使用独立草稿任务，只有人工确认后才能写入档案。DeepSeek 可直接用于抽取；知识库向量能力须另配 Embedding 服务。

本机 `web-ui` 构建后，执行 `mvn -pl zyb-app/app-starter -am package` 生成包含前端的启动 JAR。`ops/Dockerfile.release` 与 `ops/compose.release.yml` 支持将预构建 JAR 部署到仅有 Docker 的服务器。密钥只通过环境变量或受控 `.env` 提供。

面向企业内网的文档管理与 AI 知识问答平台。系统以知识库为权限边界，统一管理企业文档、组织成员、知识检索、AI 问答和审计记录。

当前版本按单企业运行，核心业务数据包含 `tenant_id`，为后续多租户隔离保留扩展能力。

## 功能模块

### 组织与权限

- 部门树和企业成员管理
- 管理员、编辑者、成员三种系统角色
- 知识库级用户授权和部门授权
- `READ`、`EDIT`、`MANAGE` 权限等级
- 允许与显式拒绝规则
- 初始密码强制修改、账号启停和登录保护

### 知识管理

- 知识库、目录和标签管理
- 富文本文章创建与编辑
- PDF、Word、Excel、PowerPoint、TXT、Markdown 和图片上传
- 文档异步解析、版本历史和版本恢复
- 全文检索与 pgvector 向量检索
- 30 天回收站和自动清理

### AI 问答

- 单知识库或多知识库问答
- SSE 流式输出
- 引用来源和原文溯源
- 会话历史与回答反馈
- 权限过滤后检索，未授权内容不会进入模型上下文
- 支持 OpenAI-compatible 聊天与 Embedding 服务
- 知识库可单独控制是否允许使用外部模型

### 系统管理

- 模型服务配置和密钥加密存储
- 系统配置管理
- 操作审计查询
- 本地磁盘或阿里云 OSS 文件存储
- Spring Boot Actuator 健康检查

## 权限模型

| 角色  | 系统职责                | 知识库权限上限  |
| --- | ------------------- | -------- |
| 管理员 | 管理组织、用户、模型、审计和全部知识库 | `MANAGE` |
| 编辑者 | 创建知识库，维护获得授权的知识内容   | `MANAGE` |
| 成员  | 阅读、搜索和使用知识库进行 AI 问答 | `READ`   |

知识库权限可以授予用户或部门。用户显式规则优先于部门规则，显式拒绝优先于允许；成员角色不会因为错误授权而获得编辑权限。

## 技术架构

- Java 21、Spring Boot 3.5
- MyBatis Plus、Flyway
- PostgreSQL 16、pgvector
- Vue 3、TypeScript、Vite、Element Plus
- OpenAI-compatible API
- Docker Compose

项目结构：

```text
.
├── web-ui/                    # Vue 管理端
├── zyb-common/                # 公共模型和工具
└── zyb-app/
    ├── api/                   # 接口对象
    ├── dal/                   # 数据访问
    ├── core/                  # 安全、存储和模型基础能力
    ├── biz/                   # 权限、文档和 AI 业务编排
    ├── web/                   # REST API 与 SPA 入口
    └── app-starter/           # 启动配置、Flyway 和镜像构建
```

## Docker Compose 部署

### 1. 环境要求

- Linux 服务器
- Docker Engine
- Docker Compose v2
- 建议从 4 核 CPU、16 GB 内存、100 GB SSD 起步
- 完整 AI 能力需要服务器可以访问配置的模型服务

如果客户服务器不能访问 Docker Hub、npm 或 Maven Central，应提前在可联网环境构建并导出镜像。

### 2. 配置环境变量

```bash
cp .env.example .env
chmod 600 .env
openssl rand -base64 48
openssl rand -base64 32
```

必须修改：

```dotenv
APP_BIND_ADDRESS=127.0.0.1
APP_PORT=8080

POSTGRES_DB=knowledge_base
POSTGRES_USER=knowledge_base
POSTGRES_PASSWORD=<数据库强密码>

JWT_SECRET=<至少48位随机密钥>
CONFIG_ENCRYPTION_KEY=<独立随机加密密钥>

APP_BOOTSTRAP_ADMIN_USERNAME=admin
APP_BOOTSTRAP_ADMIN_PASSWORD=<管理员初始强密码>

OPENAI_API_KEY=<模型服务密钥>
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_CHAT_MODEL=gpt-4.1-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```

安全要求：

- `.env` 不得提交到 Git。
- `CONFIG_ENCRYPTION_KEY` 必须单独备份，丢失后已保存的模型密钥无法解密。
- 上线后不要随意更换 `JWT_SECRET`，否则现有登录会话会失效。
- 不要使用开发或演示环境密码。
- 通过同机 Nginx 代理时保持 `APP_BIND_ADDRESS=127.0.0.1`；直接提供内网端口时填写服务器内网 IP。

### 3. 启动

```bash
docker compose config
docker compose up -d --build
docker compose ps
docker compose logs --tail=200 app
```

### 4. 健康检查

```bash
curl -fsS http://127.0.0.1:8080/actuator/health
```

预期结果：

```json
{"status":"UP"}
```

首次启动时，Flyway 会创建 `enterprise_kb` schema、安装 `vector` 扩展并初始化数据库结构。只有数据库中不存在用户且配置了 `APP_BOOTSTRAP_ADMIN_PASSWORD` 时，系统才会创建初始管理员；首次登录必须修改密码。

## 内网网关配置

推荐由企业网关或同机 Nginx 终止 HTTPS，仅向授权内网网段开放 443。PostgreSQL 的 `5432` 端口不应对办公网或公网开放。

AI 流式响应使用 SSE，Nginx 需要关闭代理缓冲：

```nginx
location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    client_max_body_size 500m;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_buffering off;
}
```

## 上线验收

- [ ] PostgreSQL 容器状态为 `healthy`，应用没有循环重启。
- [ ] Flyway 成功创建或验证 `enterprise_kb` schema。
- [ ] `/actuator/health` 返回 `UP`。
- [ ] 管理员首次登录和强制改密正常。
- [ ] 管理员、编辑者、成员的菜单和操作权限正确。
- [ ] 部门授权、用户授权和显式拒绝规则正确生效。
- [ ] 未授权用户无法搜索、读取、下载或问答对应知识库。
- [ ] 多种格式文件可以上传、解析、检索和下载。
- [ ] 文章编辑、版本恢复、删除和回收站恢复正常。
- [ ] 全文检索和向量检索正常。
- [ ] AI 流式问答、引用来源、会话历史和反馈正常。
- [ ] 禁止外部模型的知识库不会调用外部服务。
- [ ] 登录、改密和管理操作产生审计记录。
- [ ] 宿主机重启后数据库、文件和应用配置仍然存在。

单文件上传上限为 100 MB。扫描件和纯图片可以保存，但当前版本未集成高质量 OCR，可能无法生成有效的可检索文本。

## 模型与数据边界

后台“系统管理 → 模型服务”可以配置 OpenAI-compatible 服务，API Key 使用 AES-GCM 加密后存入数据库。

- 外部模型只接收权限校验和混合召回后命中的少量知识片段，不接收整篇文档。
- 标记为不允许外部模型的知识库不会调用外部服务。
- 未检索到可靠资料时，系统返回资料不足，不要求模型猜测。
- 更换 Embedding 模型或向量维度后，需要对已有文档重新向量化。

## 备份与恢复

数据库备份：

```bash
mkdir -p backups
docker compose exec -T postgres \
  pg_dump -U knowledge_base -d knowledge_base -Fc \
  > backups/knowledge-base-$(date +%Y%m%d-%H%M).dump
```

必须同时备份：

- PostgreSQL 数据库；
- `uploaded_files` 文件卷；
- `.env` 和 `CONFIG_ENCRYPTION_KEY` 的受控副本；
- 当前 Git 提交号和对应应用镜像。

数据库和文件卷应来自同一备份时间点。回滚时不要执行 `docker compose down -v`，不要删除 `postgres_data` 或 `uploaded_files`；涉及数据库迁移时，应停止应用并恢复上线前的数据库和文件卷快照。

## 本地开发

本地环境要求 Java 21、Maven 3.9、Node.js 22、PostgreSQL 16 和 pgvector。

前端：

```bash
cd web-ui
npm ci
npm run dev
```

后端：

```bash
mvn -pl zyb-app/app-starter -am -DskipTests compile
mvn -pl zyb-app/app-starter spring-boot:run
```

构建生产前端：

```bash
cd web-ui
npm run build
```

## 运维说明

- 回收站清理任务每天 02:30 执行，删除超过 30 天的记录、向量和源文件。
- 审计日志管理界面当前最多返回前 1000 条，长期运行应配置归档策略。
- 管理员可以查询审计记录，默认不能读取成员完整聊天内容。
- 修改模型或密钥配置后，执行 `docker compose up -d` 使配置生效。
- 生产环境应监控健康检查、容器状态、错误日志、数据库容量和上传文件卷容量。