> i 下载地址及更新动态见：https://mrdoc.pro/doc/46151/

**Windows部署面板**是一款用于在 Windows 上一键部署与管理 [MrDoc](https://mrdoc.pro/) 觅思文档系统的桌面工具。

它自带 **Python 3.11 运行环境**与 **MinGit**，你**无需在本机安装 Python、Git 或任何其他依赖**，通过图形界面即可完成源码获取、数据库初始化、服务启动、后台任务管理等全部操作。

- 当前版本：v1.0.0
- 适用系统：Windows 8.1 及以上（64 位）
- 无需安装：Python / Git / 数据库以外的任何运行库

---

## 1. 安装与首次启动

### 1.1 分发包内容

将收到的软件压缩包解压到任意目录，得到如下目录结构：

```
MrDocPanel\
├─ MrDocPanel.exe   面板主程序
└─ res\                   程序资源目录（必须与 exe 放在一起）
    ├─ python311.zip      Python 3.11.3 + MrDoc 全部依赖
    ├─ mingit.zip         MinGit 2.43（免安装 Git）
    ├─ logo.ico
    └─ logo.png
```

> d **重要**：`res` 文件夹必须与 `MrDocPanelAardio.exe` 位于同一目录下，请整体解压、整体移动，不要单独拷贝 exe 文件。

### 1.2 安装位置要求

请将程序解压到一个**具有写入权限的目录**，例如：

- 推荐：`D:\MrDocPanel\`
- 不推荐：`C:\Program Files\`（该目录受系统保护，面板可能无法写入运行环境与项目文件）

面板运行后会在自己的目录下创建以下内容（详见第 9 节）：

| 目录 / 文件 | 用途 |
| --- | --- |
| `runtime\` | 解压后的 Python 与 Git 运行环境 |
| `projects\` | 默认的项目（源码）存放目录 |
| `config.json` | 面板配置（自动生成） |
| `update_cache\` | 更新包下载缓存 |

### 1.3 首次启动

1. 双击 `MrDocPanel.exe` 启动面板；
2. 面板会自动检测运行环境，检测到尚未初始化时弹出提示框：
   - 点击「**立即初始化**」：解压 Python 与 Git（约 1~2 分钟，仅需一次）；
   - 点击「**稍后**」：跳过，之后可随时点击底部「**初始化环境**」按钮完成；
3. 初始化完成后，底部状态栏显示「运行环境：Python 3.11.3 已就绪 · Git 已就绪」，即可开始部署。

---

## 2. 界面导览

![](/media/202609/293ada67c02d4aeab6fd744f7b70f6f48224.png)

| 区域 | 说明 |
| --- | --- |
| 左栏 | 版本类型、项目目录、部署操作、运行设置、后台任务等部署相关设置 |
| 右栏 | 服务状态与控制按钮、实时运行日志 |
| 底栏 | 运行环境状态、「初始化环境」按钮、就绪状态、版本号 |
| 菜单栏 | 面板 / 版本 / 帮助三个菜单（详见第 6 节） |

---

## 3. 快速上手

### 3.1 开源版部署（从零到访问站点）

1. **选择版本类型**：点击左栏「**开源版**」按钮；
2. **拉取源码**：点击「**拉取 MrDoc**」，面板会用内置 Git 从 Gitee 下载 MrDoc 源码到项目目录（默认 `面板目录\projects\MrDoc`）；
3. **初始化数据库**：点击「**初始化数据库**」，等待日志提示完成；
4. **创建管理员**：点击「**创建管理员**」，按提示输入账号密码；
5. **启动服务**：点击右栏「**启动服务**」，状态灯变绿表示运行中；
6. **访问站点**：点击「**打开站点**」，浏览器会打开 `http://监听地址:端口`；
7. （可选）源码有新版时，点击「**更新项目**」在线升级（`git pull`）。

### 3.2 专业版部署

> 专业版需要你**已拥有官方专业版源码**（解压后的目录）。

1. **选择版本类型**：点击左栏「**专业版**」按钮；
2. **指定源码目录**：点击「**浏览…**」选择已解压的专业版源码目录（目录中应能看到 `manage.py`）；
   - 授权校验通过时日志提示「专业版授权验证通过」；
   - 未通过时面板会明确提示原因（如未找到 license.json、签名无效等），此时部署与运行操作不可用；
   - 请使用**新版官方专业版源码**（含授权验证模块）；旧版源码不受支持，面板会阻断并说明；
4. **初始化数据库** → **创建管理员**：同开源版；
5. **启动服务** → **打开站点**：同开源版；
6. **启动后台任务**（可选）：在「后台任务」区域点击「**启动任务**」运行异步任务队列 `run_task_worker`（详见第 5.5 节）。

> 专业版不提供在线拉取/更新源码，源码升级请在官方渠道获取新版本后重新指定目录。

### 3.3 日常使用建议

- **关闭按钮 ≠ 退出**：点击窗口右上角 [X] 只会**最小化到系统托盘**，站点服务继续运行；
- 需要彻底退出时，请使用菜单栏「**面板 → 退出**」或托盘右键菜单「**退出**」；
- 每次部署操作的进度与结果都会实时打印在右侧日志区，遇到问题优先查看日志。

---

## 4. 功能详解（左栏）

### 4.1 版本类型

| 按钮 | 说明 |
| --- | --- |
| **开源版** | 一键从 Gitee 拉取 MrDoc 开源版源码，支持「更新项目」在线升级 |
| **专业版** | 指定本地已解压的官方专业版源码目录，需授权文件，支持后台任务队列 |

### 4.2 项目目录

| 按钮 | 说明 |
| --- | --- |
| **拉取 MrDoc** | （开源版）从 Gitee 克隆 MrDoc 源码到项目目录 |
| **更新项目** | （开源版）执行 `git pull` 将源码更新到最新版 |
| **打开目录** | 在资源管理器中打开当前项目目录 |
| **浏览…** | 手动指定项目目录（专业版必用；开源版也可指向已有源码目录） |

### 4.3 部署操作

| 按钮 | 说明 |
| --- | --- |
| **初始化数据库** | 创建/升级数据库表结构（首次部署必做；源码升级后也可再执行） |
| **创建管理员** | 交互式创建后台管理员账号 |
| **安装依赖** | 按项目 `requirements.txt` 执行 `pip install`；已满足的依赖会自动跳过，不会破坏内置环境 |
| **环境检测** | 一键体检：检查运行环境、项目目录、manage.py、依赖等并给出结论 |

### 4.4 运行设置

| 设置 | 说明 |
| --- | --- |
| **runserver 开发** | Django 自带服务器，支持自动重载，适合开发调试 |
| **waitress 部署** | 多线程生产级服务器，适合正式部署使用 |
| **监听地址 / 端口** | 默认 `127.0.0.1:8000`；局域网访问可改为 `0.0.0.0` |
| **自动重载** | 仅 runserver 模式有效：修改代码后自动重启服务 |
| **使用系统代理** | 勾选后，拉取/更新源码与安装依赖会把系统 HTTP 代理传递给 git 与 pip |
| **线程数** | waitress 模式的并发线程数，默认 6 |

### 4.5 后台任务（专业版专属）

专业版的异步任务队列需要常驻进程 `python manage.py run_task_worker`，面板提供完整的运行、监控与管理：

| 能力 | 说明 |
| --- | --- |
| **运行** | 「启动任务 / 停止任务 / 重启任务」三个按钮独立控制；勾选「随服务自动启动」后，启动服务时自动拉起后台任务，停止服务时自动停止任务 |
| **监控** | 实时状态（运行中/未运行/已退出）、运行时长、进程 PID、最近活动时间；任务输出以 `[任务]` 前缀混排进主日志区 |
| **自动重启** | 勾选「崩溃自动重启」后，进程意外退出会自动重启：间隔 3 秒、最多 5 次；稳定运行 60 秒后计数自动清零；超过上限停止重启并打印告警 |

> 若「后台任务」区域显示「不可用」：① 当前是开源版（该功能为专业版专属）；或 ② 专业版源码目录中未找到 `app_task/management/commands/run_task_worker.py`，具体原因见面板提示文字。

---

## 5. 服务控制与日志（右栏）

### 5.1 服务控制

| 按钮 | 说明 |
| --- | --- |
| **启动服务** | 以当前运行设置启动站点服务，状态灯变绿 |
| **停止服务** | 停止服务（如勾选了「随服务自动启动」，后台任务一并停止） |
| **重启** | 重启站点服务 |
| **打开站点** | 用默认浏览器打开 `http://监听地址:端口` |

### 5.2 运行日志

- 服务、后台任务、部署操作的输出全部实时打印在日志区；
- 后台任务的输出带「**[任务]**」前缀，便于区分；
- 日志按级别着色：普通 / 成功（绿）/ 失败（红）；
- **清空**：清空当前日志；**复制**：复制全部日志到剪贴板；**保存**：将日志另存为文本文件，便于反馈问题。

---

## 6. 菜单栏与系统托盘

### 6.1 菜单栏

| 菜单 | 菜单项 |
| --- | --- |
| **面板(&P)** | 显示主界面 / 隐藏到托盘 / 打开项目目录 / 初始化运行环境 / **退出** |
| **版本(&V)** | **检查更新** / 自动检查更新（可勾选） / 当前版本（灰显，仅供查看） |
| **帮助(&H)** | MrDoc 官网 / Gitee 仓库 / 关于 |

### 6.2 系统托盘

- **关闭按钮 = 最小化到系统托盘**：程序继续在后台运行，服务不会中断；
- **单击托盘图标**：重新打开面板；
- **右键托盘图标**：弹出菜单——显示主界面 / 隐藏到托盘 / 检查更新 / **退出**；
- 首次隐藏到托盘时会弹出一次气泡提示；
- 托盘图标的悬浮提示会实时反映状态，例如「MrDoc部署面板 v1.0.0 · 服务运行中」。

### 6.3 退出程序

使用菜单栏「**面板 → 退出**」或托盘菜单「**退出**」：

- 点击后提示「退出面板将停止正在运行的站点服务与后台任务，然后退出程序」；
- 确认后面板会自动停止全部子进程（含 Django reloader 与 multiprocessing 子进程），**不留残留进程**；
- 点击「取消」则继续运行。

---

## 7. 版本更新

面板内置在线更新功能：

| 能力 | 说明 |
| --- | --- |
| **检查更新** | 菜单「版本 → 检查更新」（或托盘右键「检查更新」）；启动时也会自动静默检查，可通过「版本 → 自动检查更新」开关 |
| **版本显示** | 标题栏与底部均显示当前版本号；下载时底部实时显示百分比进度 |
| **更新提示** | 发现新版本时弹框显示新版本号、更新包大小与更新说明；服务端标记强制更新时会有明确提示 |
| **下载与安装** | 后台线程下载（不阻塞界面）；自动识别更新包类型（ZIP / EXE）、自动替换程序文件并**自动重启面板** |

> 更新时会**自动保留** `config.json`、`projects`、`runtime`、`update_cache`，不会覆盖您的项目数据、运行环境与配置。

---

## 8. 配置文件说明（config.json）

面板首次运行后自动生成 `config.json`，界面上的设置会自动保存到该文件，一般无需手工修改。

| 字段 | 说明 |
| --- | --- |
| `edition` | 当前版本类型：`oss`（开源版）/ `pro`（专业版） |
| `project` | 项目目录（MrDoc 源码目录） |
| `mode` | 运行模式：`runserver` / `waitress` |
| `host` / `port` | 监听地址与端口 |
| `autoreload` | 自动重载开关（runserver 模式） |
| `threads` | waitress 线程数 |
| `useProxy` | 是否把系统代理传递给 git 与 pip |
| `taskAutoStart` | 后台任务是否随服务自动启动 |
| `taskAutoRestart` | 后台任务是否崩溃自动重启 |
| `autoCheckUpdate` | 启动时是否自动检查更新 |
| `initialized` | 运行环境是否已初始化 |

---

## 9. 运行期目录结构

面板运行一段时间后，程序目录的完整结构：

```
MrDocPanelAardio\
├─ MrDocPanelAardio.exe   面板主程序
├─ res\                   程序资源（保持原样，勿删）
├─ config.json            面板配置（自动生成）
├─ runtime\               运行环境（首次初始化时自动解压）
│   ├─ python311\         Python 3.11.3 + 全部依赖
│   └─ mingit\            MinGit 2.43
├─ projects\              默认项目目录
│   └─ MrDoc\             拉取的开源版源码
└─ update_cache\          更新包下载缓存
```

> 备份或迁移时，整体拷贝程序目录即可；其中 `projects\` 与 `config.json` 是您的数据，
> `runtime\` 可删（下次启动重新初始化即可重建）。

---

## 10. 常见问题（FAQ）

**Q1：启动服务时报错「项目目录中未找到 manage.py」？**
A：开源版请先点击「拉取 MrDoc」；专业版请点击「浏览…」正确指定已解压的源码目录。

**Q2：局域网其他电脑访问不了站点？**
A：将监听地址改为 `0.0.0.0` 后重启服务，并检查 Windows 防火墙是否放行面板程序与监听端口。

**Q3：如何使用 MySQL 数据库？**
A：面板已内置 mysqlclient（官方 Windows 预编译版，无需额外安装客户端）。
修改项目中的 `config/config.ini`：

```ini
[database]
engine = mysql
name = db_mrdoc
user = mrdoc
password = 123456
host = 127.0.0.1
port = 3306
```

然后点击「初始化数据库」即可。

**Q4：「安装依赖」会破坏内置的 Python 环境吗？**
A：不会。该功能按项目 `requirements.txt` 执行 `pip install`，已满足的依赖（含 mysqlclient）会被 pip 自动跳过。

**Q5：「后台任务」区域显示「不可用」？**
A：两种可能：① 当前是开源版（该功能为专业版专属）；② 专业版项目目录中未找到 `app_task/management/commands/run_task_worker.py`。面板会在提示文字中说明具体原因。

**Q6：后台任务一直在重启怎么办？**
A：面板最多自动重启 5 次（间隔 3 秒），之后停止重启并打印告警。请查看日志中「[任务]」前缀的内容排查原因；修复后再次点击「启动任务」会重置计数。

**Q7：拉取/更新源码很慢？**
A：勾选「使用系统代理」，面板会把系统 HTTP 代理传递给 git 与 pip。

**Q8：专业版提示「授权校验未通过」？**
A：请确认授权文件 `license.json` 已放入**项目目录**（专业版源码目录）的 `license` 文件夹内，且使用的是新版官方专业版源码。仍无法通过时，请把日志通过「保存」导出后联系技术支持。

**Q9：如何重新解压运行环境？**
A：点击底部「初始化环境」按钮，确认后会删除并重新解压（会清除已安装的额外依赖）。

**Q10：点击 [X] 后程序去哪了？**
A：最小化到了系统托盘，服务仍在运行。双击托盘图标可找回面板；要彻底退出请用菜单「面板 → 退出」或托盘右键「退出」。

**Q11：更新面板会覆盖我的项目数据吗？**
A：不会。更新只替换程序文件，`config.json`、`projects`、`runtime`、`update_cache` 均完整保留。

**Q12：「检查更新」提示“当前没有已发布的新版本”？**
A：说明更新服务端尚未发布该产品的版本（或该平台暂无安装包），属于正常状态。

---

## 11. 故障排查速查

| 现象 | 排查步骤 |
| --- | --- |
| 双击 exe 无反应或报错 | 确认 `res` 文件夹与 exe 在同一目录；确认程序位于可写目录（勿放 Program Files） |
| 服务启动失败 | 查看日志区红色错误；检查端口是否被占用（更换端口重试）；点击「环境检测」确认环境就绪 |
| 页面打不开 | 确认服务状态灯为绿色；确认地址端口与设置一致；换 `0.0.0.0` 监听后用 `http://本机IP:端口` 访问 |
| 初始化数据库失败 | 先做「环境检测」；使用 MySQL 时检查 `config/config.ini` 与数据库可达性 |
| 拉取源码失败 | 勾选「使用系统代理」重试；确认网络可访问 gitee.com |
| 专业版按钮禁用 | 授权校验未通过，按 Q8 处理 |
| 其他异常 | 日志区「保存」导出日志文件，连同操作步骤反馈给技术支持 |

---

*本文档对应面板版本 v1.0.0。功能与界面如有更新，请以程序实际界面与随包说明为准。*

Windows 部署面板