如果你正在用宝塔面板又想在服务器上搭一个属于自己的在线文档系统那么 Mrdoc 这个开源项目值得花点时间折腾。Mrdoc 是 Python 写的基于 Django 框架多用户、支持 Markdown 编辑、文档整理、全文搜索拿来做个人知识库或者小团队内部文档库都挺合适。宝塔面板里的 Python 项目管理器 2.0正好是把 Python 项目部署从“命令行写 systemd 手工维护虚拟环境”这种事情简化成了一个可视化面板操作的事。前阵子一个朋友跟我说他用宝塔面板装 Mrdoc 折腾了整整两天没跑起来。我远程一看问题其实不复杂项目路径选错了层数据库账号授权也没做对。这类问题如果第一次接触确实很容易反复卡住。所以这篇就把我从零到一部署 Mrdoc 的过程完整梳理一遍尤其是 Python 项目管理器 2.0 里每个字段该怎么填、哪些操作能自动化、哪些事还是得手动做都讲清楚。适合刚用宝塔面板不久、想把 Python 项目跑起来的人参考。需要先说清楚一点Python 项目管理器 2.0 不是“安装完 Python 环境”就完事它更像一个项目生命周期管理工具从创建虚拟环境、安装依赖、启动进程到查看日志和开机自启都能在界面里完成。这篇中的每一步我都会解释为什么这么做而不是只给一串命令。1. 为什么用宝塔Python管理器2.0部署Mrdoc选型理由和部署路径1.1 Mrdoc 适合什么场景Mrdoc 在开源文档系统里算是比较轻量的一类。它不像语雀、云笔记那样依赖第三方服务所有数据都在自己的服务器上。你注册账号后可以创建文集、编写 Markdown 文档、上传图片、管理文档标签还带全文搜索和文档评论。对于需要沉淀内部知识库的小团队来说这种“数据完全私有”的优势非常明显毕竟把公司内部文档放到别人的SaaS上不少人心里还是会打鼓。从技术角度看Mrdoc 对服务器配置的要求并不高1核1G 的入门云主机就能跑得很流畅。但有一个前提条件你得把 Python 环境、数据库、反向代理这些东西都安排明白。这正是很多新手在部署时最大的障碍——项目本身不复杂复杂的往往是部署链路。1.2 用Python管理器2.0替代传统systemd方案传统的 Python 项目部署流程大致是这样的编译安装 Python、创建 virtualenv 或 venv、pip 安装项目依赖、写一个 systemd service 文件、设置环境变量和启动命令、再处理日志轮转和开机自启。这套流程熟练的人操作起来半小时能完成但对没什么 Linux 经验的人来说每一步都可能出问题尤其是编译安装 Python 时系统缺少依赖库报错信息还不一定看得懂。宝塔面板的 Python 项目管理器 2.0 把这些打包成了一个流程。它在界面上帮你做四件核心的事管理多个 Python 版本不用自己编译。每个项目自动创建独立的虚拟环境项目之间不互相干扰。面板直接启动、停止、重启项目进程还能看运行日志。支持开机启动设置服务器重启后项目自动拉起。用这个插件部署 Mrdoc等于把整个部署过程从“系统运维”降级成了“填表操作”你只需要聚焦在项目本身需要做的事准备代码、配好数据库、安装依赖。1.3 完整部署路径我这次部署采用的路径如下后面几节都按照这个顺序展开确认宝塔面板环境和 Linux 发行版信息。安装 Python 项目管理器 2.0 插件并预装 Python 3.8 版本。创建 MySQL 数据库和专用账号上传 Mrdoc 源码到项目目录。修改 Mrdoc 的数据库配置。用虚拟环境执行依赖安装和数据迁移创建超级管理员账号。在 Python 项目管理器 2.0 中添加项目把运行进程交给面板管理。配置 Nginx 反向代理和 HTTPS 证书。处理几个部署后最常遇到的坑。这个顺序是有讲究的先准备数据库和代码再配置和迁移数据最后交给面板去管理运行。很多人失败是因为顺序反了项目添加进去才想起来数据库没建或者依赖还没装完就直接点启动结果面板上显示运行中实际上访问页面全是报错。2. 环境准备面板、数据库、源码目录一次配齐2.1 确认系统和面板版本我用的服务器是 CentOS 7.9宝塔面板 7.9 免费版。系统选择没有太大限制Ubuntu 20.04、Debian 11 也都行Python 项目管理器 2.0 官方插件对这几种常见系统的兼容性都做过适配。在动手之前先用命令确认一下系统的基本信息比较稳妥cat /etc/os-release df -h /www free -m这里我重点看两个东西磁盘空间和内存。Mrdoc 的依赖包加上 Python 虚拟环境整体占用大约 1GB 左右如果磁盘快满了后面安装依赖会莫名其妙失败。内存方面如果你用的是 512MB 的小机器建议先开一点 swap否则 pip 安装编译型依赖包时容易出现进程被 OOM Killer 直接杀掉的情况。2.2 安装Python项目管理器2.0并预装Python版本打开宝塔面板的“软件商店”搜索“Python项目管理器”安装 2.0 版本。安装速度取决于服务器网络一般一两分钟就完成。安装完成后先不要急着添加项目先设置 Python 版本。在插件首页点击“版本管理”选择安装 Python 3.8 或者 3.9。Mrdoc 对 Python 3.8 以上版本支持很好我这次选的是 3.8。如果插件默认已经带了版本就不用重复安装。预装 Python 版本这一步有两个容易被忽略的地方插件会让你选“安装版本”时同时指定安装路径默认装在系统 /root/.pyenv 或者 /www/server 下。如果你在之前的教程里自己手动编译安装过 Python两者可能共存使用时要看插件里选的到底是哪个版本。Python 版本管理器安装的过程其实也是编译过程需要几分钟期间不要关闭页面。装完之后建议把插件版本更新到最新旧版本偶尔有进程管理的小 bug。2.3 创建MySQL数据库和专用账号Mrdoc 支持 SQLite 和 MySQL 两种数据库。SQLite 零配置适合快速体验但如果你准备长期使用存放大量文档数据和附件MySQL 更可靠查询效率也更高。这次部署我用的是 MySQL。在宝塔面板中进入“数据库”菜单添加一个数据库。这里要注意几个细节数据库名建议用mrdoc字符集选utf8mb4。Mrdoc 文档内容普遍是中文而且是 Markdown里面还可能含有 emoji 符号。如果使用默认的utf8字符集数据中包含四字节 emoji 字符时插入会报错所以我强烈建议直接用utf8mb4。用户名单独创建一个不要直接用宝塔面板默认的数据库管理账号去跑应用。创建的时候访问权限选择“本地服务器”即可。Mrdoc 和应用跑在同一台服务器上通过本机连接数据库根本没有必要开放公网访问权限这样可以少一个被攻击的入口。创建之后记录下数据库名、用户名和密码。密码如果太复杂建议分开存放在本地笔记里避免在面板里反复输入还搞混。2.4 上传Mrdoc源码到项目目录Mrdoc 的源码托管在 GitHub 和 Gitee 上。从 GitHub 直接拉取在国内服务器上速度可能不稳定我更推荐先在本地电脑把源码下载成 zip然后通过宝塔的“文件”功能上传到服务器这样最省心。上传目标目录我建议放在/data/www/Mrdoc。为什么不用默认的/www/wwwroot因为那个目录通常是给 Web 站点用的里面放 Nginx 站点配置和静态文件Mrdoc 的 Python 源码放在那里反而容易和站点文件混淆。/data/www单独建一个应用目录结构更清晰。上传完成后用文件管理解压 zip确认项目根目录下有manage.py文件。这一步很重要后面项目路径就是指向这一层。很多人在这一步选错了路径指向了外层解压目录导致 Python 管理器启动时找不到 Django 应用。解压完成后右键项目目录把属主设置为www。宝塔的 PHP 和 Nginx 默认运行用户一般是www虽然 Mrdoc 的进程最终由 Python 管理器启动但统一权限能避免后续写临时文件和日志时出现 Permission denied 的问题。3. 修改数据库配置并完成数据迁移3.1 找到并修改配置文件Mrdoc 的配置文件和普通 Django 项目不太一样它在项目根目录下有一个config文件夹或者独立配置文件具体文件路径不同版本略有差异。稳妥的做法是先打开项目的 README 或者部署文档里面会明确告诉你当前版本该改哪个文件。以我部署的版本为例数据库连接信息就在配置文件的DATABASE_*这一组字段里。核心要改的包括DATABASE_NAME mrdoc DATABASE_USER mrdoc_user DATABASE_PASSWORD 你的数据库密码 DATABASE_HOST 127.0.0.1 DATABASE_PORT 3306有几个容易踩的细节需要特别说明一下。DATABASE_HOST建议直接填127.0.0.1不要填localhost。虽然大多数情况下两者都能连上但 Python 的 MySQL 驱动在解析localhost时可能会走 socket 文件而 MySQL 配置的 socket 路径如果不对应用就会报Cant connect to local MySQL server。直接用127.0.0.1会让驱动走 TCP 连接能避开这个问题。数据库密码如果包含#、$、这些特殊字符在 Python 配置文件中字符串里直接写一般是没问题的但如果你之后在 Shell 命令行里激活虚拟环境手动测试连接记得对特殊字符做转义否则 Shell 会把密码的一部分截断。修改完配置后保存文件。有些版本还有DEBUG选项测试阶段可以打开方便看到报错页面但正式上线前一定要改成关闭状态否则会泄漏服务端路径和配置信息。3.2 用虚拟环境执行依赖安装和迁移命令Mrdoc 的依赖清单在项目根目录下的requirements.txt文件里里面包含 Django、MySQL 驱动、Whoosh、Pillow 等一堆常用的 Python 库。依赖安装在面板里也可以做但我更建议第一步先通过命令行手动完成原因很简单面板的“安装依赖”按钮会把输出信息收进虚拟环境的日志里一旦某个包安装失败新手很难分清是网络问题、编译问题还是版本冲突问题。命令行操作前先定位 Python 项目管理器 2.0 为这个项目创建的虚拟环境路径。你可以在插件界面里找到环境路径通常是/www/server/pyporject_evn/Mrdoc或者类似命名。然后执行source /www/server/pyporject_evn/Mrdoc/bin/activate激活之后在当前 Shell 里执行的 Python 和 pip 都指向虚拟环境。这个细节非常关键我以前就吃过亏在没激活虚拟环境的情况下执行pip install -r requirements.txt结果包全部装到了系统 Python 里面板启动项目后照样找不到依赖。接下来进入项目目录安装依赖cd /data/www/Mrdoc pip install -r requirements.txt安装过程可能会持续几分钟看到类似Successfully installed django-xx的提示就说明成功了。如果某个包编译失败通常缺的是系统级依赖库这个我在后面第六节单独讲。依赖装好后先执行数据库迁移python manage.py makemigrations python manage.py migrate第一条命令是生成迁移文件第二条是把表结构写入 MySQL。看到Applying 某张表 ... OK这类输出说明数据库连接和迁移都正常。如果这一步连不上数据库那问题一定出在上一节修改的配置上优先检查DATABASE_HOST、DATABASE_USER和密码是否对应。3.3 创建你的管理员账号数据库迁移完成后项目表已经建好接下来创建超级管理员python manage.py createsuperuser按提示输入用户名、邮箱、密码即可。密码不要设置得太简单因为后台能管理所有用户和文档。这一步执行时如果提示Username is already taken说明你之前已经创建过账号可以直接登录不需要重复执行。到这里Mrdoc 的数据库部分已经全部就绪。你可以临时用python manage.py runserver 0.0.0.0:8000试一下能不能访问但我不建议长期用 runserver 跑生产环境它的性能和处理并发能力都不行。正确做法是接下来把这个项目正式交给 Python 项目管理器 2.0。4. 把Mrdoc交给Python管理器2.0添加项目与进程管理4.1 “添加项目”面板每个字段怎么填打开 Python 项目管理器 2.0点击“添加项目”会看到一个表单重点字段如下项目名称随意建议填Mrdoc。项目路径选择到/data/www/Mrdoc即包含manage.py的目录。Python版本选择之前预装的 3.8。框架选择 Django。启动方式这里我选择“自定义”后续填启动命令。启动命令填python manage.py runserver 0.0.0.0:8000。运行用户选择www。程序端口8000。开机启动建议勾选。项目路径一定要检查仔细路径错了面板启动时根本找不到manage.py会直接报No module named config之类的错误。框架选项选 Django 之后部分版本的面板会自动生成 Gunicorn 或 uWSGI 的启动模板但为了降低第一次部署的不确定性自定义启动命令更直观。关于用runserver而不是 Gunicorn我是这样考虑的第一Mrdoc 在开发模式下功能完整图片上传、静态文件、后台管理都能正常跑第二Django 的runserver在调试报错信息时更友好。等你把整个流程跑顺之后再去切换到 Gunicorn 或者其他 WSGI 服务器处理生产流量这是完全合理的进阶路线。4.2 启动、日志、重启操作添加项目后回到项目列表可以看到刚才添加的 Mrdoc 记录后面有“启动”“日志”“重启”“删除”等操作按钮。点一次“启动”面板会自动完成两件事创建/复用虚拟环境中的 Python 解释器然后用之前填的启动命令把进程拉起来。启动之后页面通常会显示“运行中”。很多人这时候直接打开域名访问发现打不开然后就慌了。别急先验证基础链路通不通。在终端执行curl -I http://127.0.0.1:8000如果能收到 HTTP 响应说明 Mrdoc 服务进程已经正常监听在 8000 端口问题只可能出在 Nginx 反代层。如果 curl 没反应则说明面板显示“运行中”并不代表进程真的存活这时候点开“日志”按钮看具体报错最常见的几种是端口被占用、虚拟环境里依赖缺失、项目路径选错。这是一个非常关键的排查顺序先本地 curl再看日志最后才动反向代理配置。否则很容易在前端和后端之间反复横跳浪费时间。4.3 开机启动和进程守护细节Python 项目管理器 2.0 的开机启动功能实际上是通过往系统服务管理器里注册一个自定义服务来实现的。勾选之后CentOS 7 上会生成一个 systemd service服务器重启后自动拉起这个项目。但有一点要注意如果启动命令写得不对开机自启功能虽然注册成功重启后照样起不来。所以建议你在确认项目的确能正常手动启动后再重启一次服务器做验证。很多时候人们以为启动失败了其实只是服务拉起来后又崩了日志里能看到一行Address already in use。另外面板虽然能管理项目进程但它不是万能的。如果 Mrdoc 进程因为内存不足被系统 OOM Killer 杀掉面板上的状态可能还停留在“运行中”直到下一次点击操作才会被纠正。遇到被杀的迹象比如日志里断崖式停止、再无新请求进来就直接点“重启”并在服务器上查一下内存和 swap 的使用量。5. Nginx反向代理与HTTPS收尾5.1 建立站点并配置反向代理Mrdoc 的 Django 应用监听在 8000 端口不可能直接让用户通过 IP 加端口方式访问一来不安全二来不专业。正确做法是配置 Nginx 反向代理让 80 和 443 端口的请求转发到 8000。在宝塔面板“网站”菜单添加一个站点域名填你解析好的真实域名。不需要勾选“创建 FTP”和“创建数据库”因为数据库已经在前面建好。添加完成后进入站点的“反向代理”配置添加一条代理规则目标 URL 填http://127.0.0.1:8000。宝塔会自动生成一段 Nginx 配置本质上和我手动配置的效果一样。如果你的宝塔版本没有这个可视化入口也可以直接在站点配置里写location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_read_timeout 120s; }这里几个proxy_set_header字段值得说一下。Host字段如果不设置Mrdoc 拿到的请求头里 Host 可能是127.0.0.1:8000会导致 Django 的 ALLOWED_HOSTS 校验失败直接返回 400。X-Forwarded-Proto的作用是让 Django 知道用户是通过 HTTPS 访问的否则在后台生成的一些链接可能会错误地使用 HTTP。5.2 静态文件处理Mrdoc 的静态资源包括 CSS、JS、图片等。默认情况下Django 的runserver能自己处理静态文件转给 Nginx 反代后也能透传正常情况下页面能正常加载。但如果后续你转到 Gunicorn 或者 uWSGI就必须让 Nginx 直接处理静态文件否则这些服务器的静态文件处理能力很弱并发上来后页面会明显变卡。做法分两步。第一步在 Mrdoc 项目目录下执行python manage.py collectstatic这个命令会把所有 Django 应用的静态文件收集到项目配置的静态目录中。然后在 Nginx 配置里加一条静态文件路径的映射指向那个目录。不同版本的 Mrdoc 静态目录路径不太一样你可以看收集完成后输出信息里的路径地址把 Nginx 的location /static/指向它。5.3 HTTPS证书和禁用TLS1.0/1.1现在部署 Web 服务HTTPS 几乎是必选项。在宝塔站点设置里找到“SSL”选择 Let‘s Encrypt 证书勾选域名申请。宝塔会自动配置证书并开启 HTTPS不需要手动修改 Nginx 配置确实省了很多事。申请完证书后有一个容易被忽视的安全配置TLS 协议版本。老版本 TLS 1.0 和 TLS 1.1 存在已知的协议漏洞宝塔新版默认配置模板已经禁用了它们但如果你是从旧版本面板升级上来的配置文件里可能还保留着旧协议。检查站点配置中的ssl_protocols一行确认只保留 TLSv1.2 和 TLSv1.3ssl_protocols TLSv1.2 TLSv1.3;同时建议开启 HSTS让浏览器只允许通过 HTTPS 访问这个站点降低中间人攻击风险。宝塔面板的 SSL 设置界面里有 HSTS 选项勾选后保存即可。6. 实测中翻车最狠的几个坑6.1 数据库连接被拒八成是账号授权问题Mrdoc 部署过程中遇到最多的报错就是数据库连接失败表现形式是页面 500日志里写着Can’t connect to MySQL server或者Access denied for user。第一个问题通常出在DATABASE_HOST上改成127.0.0.1基本能解决。第二个问题也就是Access denied原因往往是 MySQL 账号的 host 匹配不对。你在宝塔“数据库”菜单创建账号时如果选了“允许任意主机访问”MySQL 里生成的用户可能是mrdoc_user%这个没关系能访问但如果你选了“仅本机”生成的是mrdoc_userlocalhost而 Django 通过 TCP 用127.0.0.1连接时MySQL 会尝试匹配mrdoc_user127.0.0.1匹配不到就拒绝访问。解决办法是进入 phpMyAdmin 或者命令行给这个账号再补一条授权GRANT ALL PRIVILEGES ON mrdoc.* TO mrdoc_user127.0.0.1 IDENTIFIED BY 你的密码; FLUSH PRIVILEGES;这条操作在官方文档里不一定写但实际部署中遇到概率很高属于典型的环境配置坑。6.2 面板显示运行中但打不开先探端口Python 项目管理器 2.0 偶尔会出现“过一会儿进程自己挂了但面板状态还悬在运行中”的情况。这时候别反复点重启先做两件事。ps -ef | grep python netstat -tlnp | grep 8000第一检查进程是否存在第二检查端口是否还在监听。如果进程消失看日志文件重点搜Traceback和MemoryError。如果端口还在监听但网站打不开那就把排查看从项目层转到 Nginx 层检查站点配置是否生效、域名解析是否正确。我在一次部署中还遇到过很隐蔽的端口冲突问题面板把项目添加进去时填了 8000 端口但实际上有个旧进程早就占了 8000新进程每次启动都被系统拒绝面板却显示“已停止”和“运行中”来回跳。清理旧进程后重新启动问题迎刃而解。6.3 依赖安装失败常见系统库缺失如果pip install -r requirements.txt在编译Pillow、lxml、cffi这类包含原生代码的包时失败不要急着换 pip 源更不要用什么复杂方案先检查系统库。CentOS 下常见缺yum install -y libjpeg-turbo-devel zlib-devel libffi-devel openssl-develUbuntu 和 Debian 则是apt install -y libjpeg-dev zlib1g-dev libffi-dev libssl-dev装完系统库后重新执行pip install -r requirements.txt。这一步经历了太多次以前在 512MB 内存的小服务器上装 Pillow明明系统库全齐了仍然被杀加了 swap 之后问题解决可见小内存机器先加 swap 是有多必要。如果因为网络原因依赖包下载超时可以临时指定国内 pip 源这个操作里最实在的一句是先确认虚拟环境已经激活否则换源也是白换。6.4 502与静态文件404Nginx 反代配置完成后最常见的现象是 502 Bad Gateway。502 的本质是 Nginx 把请求转发到127.0.0.1:8000时后端的 Django 进程没有应答。大概率是 Mrdoc 进程根本没起来验证方式还是用 curl 本地访问。如果 curl 正常但 Nginx 依然 502才需要检查proxy_pass的地址是不是写错、端口是不是和面板里设置的一致。静态文件 404 的问题一般发生在执行了collectstatic之后。常见的错误是 Nginx 里alias的路径写错了少了一个斜杠或者路径末尾多了一层子目录。检查时最直接的方法是curl -I http://你的域名/static/css/某个文件路径看实际返回的状态码和 Nginx 错误日志通常一下子就能定位。最后再说一点整个流程走下来我的体会是用宝塔 Python 管理器 2.0 部署 Mrdoc 本身不难难的是理解每一步在做什么。项目管理器帮你省掉了写 systemd 和手动管理虚拟环境的麻烦但数据库连接、Django 配置、Nginx 反代这三件事终究还是要你有基本的概念。把这篇文章里的每一个验证动作自己动手跑一遍远比照着别人的成功截图重做一遍更有收获。最后一个实用建议部署成功后立刻去宝塔面板的计划任务里加一个“网站备份”任务每天把/data/www/Mrdoc目录和 MySQL 数据库备份一次。文档系统的数据是你自己的财产等某天误操作删了某个账号你会发现备份是当时唯一能拯救你的东西。