# ZenCloud-Pro

**Repository Path**: wp-zhao/zencloud-pro

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZenCloud-Pro —— 政务门户与综合办公系统

> 一套代码两个面：**对外门户网站**（国内政务风格，未登录可访问）+
> **对内综合办公系统**（公文流转、工作登记、通知通告、日程会议、AI 问答）。
> 以文件与知识库为底座，轻量部署、权限分级、全程可审计。

---

## 一、功能总览

### 门户网站（对外，`/portal`）

| 能力 | 说明 |
|---|---|
| **首页** | 图片轮播 + 通知公告 + 头条要闻 + 工作动态 + 政务公开 + 办事服务 + 专题专栏 + 页脚备案，标准政务版式 |
| **内容** | 文章发布/编辑（富文本 + 图片）、栏目管理、置顶、草稿/发布/下架、定时生效 |
| **公开控制** | 每篇文章、每条通知都可单独选择**是否公开**；未公开的内容前台永远查不到 |
| **与通知通告呼应** | 门户「通知公告」栏目**直接读取**通知通告中勾选了「公开到门户」的条目，数据只存一份，改一处两边同步 |
| **图片轮播** | 增删改、排序、跳转链接、定时启停 |
| **站点设置** | 站名、徽标、标语、宣传语、热门搜索词、主导航入口、办事服务图标、友情链接、页脚与备案信息 |
| **配色方案** | **所有区块的颜色（含轮播等图片承载区）均可后台配置**，内置「政务红 / 公安蓝 / 生态绿 / 水墨灰」预设，保存即生效、无需重新构建前端 |
| **门户图库** | 文章配图与轮播图统一入库，与 OA「文件管理」物理隔离，不污染用户文件/版本/回收站 |

> 门户访问入口：`http://服务器IP/portal`；右上角「登录」进入 OA。
> 门户维护入口：OA 登录后「系统配置 → **门户管理**」（需 `portal.manage` 权限，默认管理员有）。

### 综合办公模块

| 模块 | 能力 |
|---|---|
| **看板** | 通知、待办公文、今日日程聚合；管理员与组长可看范围内的工作登记统计 |
| **通知通告** | 发布、阅读并自动标记已读、置顶、下架，**可勾选「公开到门户」** |
| **通讯录** | 按部门/分组查询同事的姓名、职务、办公地址、电话、邮箱 |
| **日程/会议** | 个人日程、会议室预约与时间冲突自动检测 |
| **公文管理** | 收文登记 → 送批 → 批办/转办 → 办结 → 归档；发文拟稿 → 审核 → 签发/退回 → 归档 |
| **文件管理** | 版本控制、重复秒传、大文件分片上传、分组共享、回收站、在线预览与编辑、AI 索引 |
| **工作登记** | 分类与登记模板、多维度筛选、Excel 导出、统计概览 |
| **AI 助手** | 基于单位知识库的智能问答，流式输出，答案标注引用来源可溯源 |
| **我的日志** | 个人操作记录；管理员另有全站日志审计 |
| **系统配置** | 用户、分组、功能开关、权限设置、**门户管理**、AI 配置、参数、预览引擎、回收站、日志审计 |

> 每个模块对应一个**功能开关**，管理员可在「系统配置 → 功能开关」中启停并调整菜单顺序。
> 关闭后普通用户的菜单与入口全部隐藏，**管理员不受影响**，仍可进入并重新开启。
> 「看板」与「系统配置」恒开启，保证系统始终可用可维护。
> 门户前台是公开站点，不受功能开关约束；「门户管理」菜单可单独关闭。

---

## 二、快速开始

### 1. 部署（Docker Compose，推荐）

```bash
cp .env.docker.example .env          # Windows: copy .env.docker.example .env
docker compose up -d --build
docker compose ps                    # 确认容器均为 Up/healthy
curl -s http://localhost:8000/api/health
```

浏览器访问 `http://服务器IP`（默认前端端口 80），使用初始账号登录
（用户名默认 `admin`；口令取 `.env` 中的 `ADMIN_PASSWORD`，未配置或为弱口令时
由系统首次建库随机生成，打印到后端启动日志并写入数据目录
`initial_admin_password.txt`，**首次登录强制修改密码**后该文件自动删除）。

管理员可在「系统管理 → 参数配置」页调整单文件大小上限（默认 5 GB）、登录锁定策略、
会话有效期、密码最小长度、回收站保留天数等，保存即时生效。

> ⚠️ 部署前**必须**修改 `.env` 中的 `SESSION_SECRET`、`ONLYOFFICE_JWT_SECRET`、`POSTGRES_PASSWORD`。
> 模板 `.env.docker.example` 中这三项**故意留空**：留空或填入弱值（如示例占位符、少于 32 位），
> 后端与 compose 都会**拒绝启动**并提示生成方法（安全闸门，防止照抄模板）。
> 生成方式：`python -c "import secrets;print(secrets.token_urlsafe(48))"`

### 2. 初始化

```
建分组（部门） → 建用户并设角色 → 设分组组长 → 检查功能开关与权限 → 配置预览引擎 → 发布首条通知
```

### 3. 日常运维

| 目的 | 命令 |
|---|---|
| 看状态 | `docker compose ps` |
| 看日志 | `docker compose logs -f backend` |
| 重启某服务 | `docker compose restart backend` |
| 更新代码后重建 | `docker compose up -d --build` |
| 停止（保留数据） | `docker compose down` |
| 备份 / 恢复 | `bash docker/backup.sh` / `bash docker/restore.sh <备份包>` |

> ⚠️ **从旧版本升级（容器名变更）**：本次发布把镜像与容器名从 `zencloud-*`
> 统一为 `zencloud-pro-*`。`container_name` 变了，直接 `up -d` 会因**端口占用**
> 失败（旧容器仍占着 80/8000）。升级步骤：
>
> ```bash
> docker compose down          # 先停掉旧容器（数据卷保留，不会丢数据）
> docker compose up -d --build # 再用新名字起
> ```
>
> 数据卷名由项目目录名派生，目录仍是 `ZenCloud-Pro`，因此**数据不受影响**。
> 若曾用脚本备份过，`docker/restore.sh` 的 `PG_CONTAINER` 默认值已同步改为
> `zencloud-pro-postgres`；恢复**旧备份**时需显式指定旧容器名：
> `PG_CONTAINER=zencloud-postgres bash docker/restore.sh <备份包>`。
> 数据库名与数据库用户仍为 `zencloud`（改动涉及数据迁移，刻意保持不变）。

> 若报 `docker: 'compose' is not a docker command`，本机没有 Compose V2 插件，
> 改用独立版 `docker-compose`，参数完全一致。

### 4. 离线部署（内网交付）

```bash
# 联网机：构建 → 导出镜像包（约 5.4 GB，含 5 个运行期镜像）
docker compose up -d --build
bash docker/export-images.sh            # Windows：docker\export-images.bat

# 目标机：导入 → 免构建启动
bash docker/load-images.sh              # 或 docker load -i offline/images/zencloud-pro-offline-images-1.0.0.tar.gz
cp .env.docker.example .env             # 并按上文修改三个密钥
docker compose up -d --no-build         # 关键：--no-build，禁止联网构建
```

> 离线包**只含运行期镜像、不含构建基础镜像**，目标机只能免构建启动。
> 完整步骤、验证清单、已知坑（如旧版包 `unrecognized image format` 的处置）
> 与安全加固见《部署运维人员说明》第四章。

---

## 三、角色与文档

系统内置四类角色，数据可见范围与可用功能各不相同：

| 角色 | 定位 | 可见范围 |
|---|---|---|
| **工作人员** | 一般干部、办事人员 | 本人数据 |
| **组长** | 科室负责人、专班组长 | 本人 + 分管分组的成员数据 |
| **领导** | 单位领导、分管领导 | 全站文件与全部公文 |
| **管理员** | 系统管理员（建议 1~2 人） | 全部数据 + 全部系统管理功能 |

**请按角色查阅文档**（全部位于 `docs/`）：

| 角色 | 文档 |
|---|---|
| 管理员 | [docs/使用手册/01-管理员使用手册.md](docs/使用手册/01-管理员使用手册.md) |
| 管理员（门户内容与配色） | [docs/使用手册/06-门户网站管理说明.md](docs/使用手册/06-门户网站管理说明.md) |
| 领导 | [docs/使用手册/02-领导使用说明.md](docs/使用手册/02-领导使用说明.md) |
| 组长 | [docs/使用手册/03-组长使用说明.md](docs/使用手册/03-组长使用说明.md) |
| 工作人员 | [docs/使用手册/04-工作人员使用说明.md](docs/使用手册/04-工作人员使用说明.md) |
| 部署运维 | [docs/使用手册/05-部署运维人员说明.md](docs/使用手册/05-部署运维人员说明.md) |
| 验收/审计 | [docs/交付验收/05-全量代码审计报告.md](docs/交付验收/05-全量代码审计报告.md) |

文档总入口：[docs/README.md](docs/README.md)

---

## 四、技术栈

| 端 | 技术 |
|---|---|
| 后端 | Python 3.12 / FastAPI / SQLAlchemy 2.0 / PostgreSQL + pgvector / loguru |
| 前端 | Vue 3 + Vite + Element Plus + Pinia + vue-router；富文本用 wangEditor 5 |
| 在线编辑 | OnlyOffice Document Server（可选组件） |
| AI | Ollama（内置 Embedding，qwen3-embedding:0.6b）+ 任意 OpenAI 兼容 LLM，SSE 流式输出 |
| 部署 | Docker Compose（唯一部署方式），支持离线镜像包交付 |

---

## 五、目录结构

```
ZenCloud-Pro/
├── backend/              # FastAPI 后端
│   ├── app/routers/      # 19 个业务路由模块（143 个端点）
│   ├── app/ai/           # AI 子系统：索引/检索/任务/抽取/模型接入
│   ├── app/preview/      # 预览与编辑引擎插件
│   ├── migrations/       # Alembic 数据库迁移
│   └── tests/            # pytest（独立 PostgreSQL 测试库）
├── frontend/             # Vue3 前端（Nginx 托管 + /api 反代）
├── docs/                 # 交付文档：使用手册（分角色）+ 审计报告 + 参考文档
├── docker/               # 构建、导入导出、备份恢复脚本
├── ci/                   # CI 流水线脚本
├── scripts/              # 冒烟测试等辅助脚本
├── Dockerfile / docker-compose.yml / .env.docker.example
└── README.md
```

---

## 六、安全与合规说明

- 全部关键操作写入审计日志，日志**只追加、无删除接口**，满足事后追溯要求。
- 账号由管理员统一创建，**不开放自助注册**（默认关闭）。
- 会话采用无状态 JWT，默认有效期 12 小时，支持登出失效黑名单。
- 登录失败限速，防暴力枚举。
- 密钥与口令不回显、不入库；`.env` 已纳入 `.gitignore`。
- 关键密钥（会话签名 / OnlyOffice 验签）三重安全闸门：留空、弱值、短值一律拒绝启动。
- 数据库与文件存储的备份由 `docker/backup.sh` 提供（含卷名探测与恢复校验），**请定期演练恢复**。
- AI 回答内容经 DOMPurify 净化，阻断 XSS。

> 当前版本的代码审计结论、缺陷清单与整改状态见
> [docs/交付验收/05-全量代码审计报告.md](docs/交付验收/05-全量代码审计报告.md)。
> 系统面向**内网受控环境**交付；政务采购级部署还需补充等保测评、国密算法与信创适配。