先说结论在宝塔面板上用Python管理器2.0装Mrdoc是自建在线文档系统里最省心的一条路。Mrdoc这东西对个人开发者太友好了纯开源、支持Markdown语法、自带目录和全文搜索部署在自己服务器上数据完全可控不用怕第三方知识库哪天停服或者审核抽风。而宝塔的Python管理器2.0正好把原来那套“SSH进去建虚拟环境、pip装依赖、手写systemd守护进程”的流程全部可视化环境隔离、日志查看、进程守护都能在面板里点鼠标搞定。这篇文章我直接把完整实操流程和踩过的坑都写出来适合用过宝塔但没怎么碰过Django项目的人照着走就能把Mrdoc跑起来。1. 为什么我用Python管理器2.0来跑Mrdoc1.1 Mrdoc到底是什么适合谁用Mrdoc是一个基于Python Django开发的在线文档系统很多人叫它“MrDoc”本质上就是一个支持Markdown语法的知识库管理工具。它跟语雀、Notion这类产品定位相似但最大的区别是自托管、纯开源数据和文件全部在自己服务器上不受第三方平台限制。对于个人开发者、小型技术团队、或者有文档整理强迫症的人来说Mrdoc非常合适。你可以拿它记接口文档、做项目Wiki、整理学习笔记甚至可以当作小型团队的知识库来用。它内置了项目分类、文档目录树、全文搜索、图片上传、文档导出这些核心功能日常使用完全够了。和WordPress那种博客系统不一样Mrdoc的定位更偏向“工作型文档管理”目录结构清晰层级关系明确适合长期积累文档的场景。1.2 直接部署和面板管理器到底差在哪大部分人第一次接触宝塔的时候默认思路都是SSH登录服务器用命令行创建虚拟环境手动安装依赖再写一个systemd服务文件来管理进程。这套流程对老手来说问题不大但存在几个实际痛点第一Django项目跑起来之后环境变量、启动参数散落在各配置文件里时间一长很容易忘记当时怎么配的第二日志默认输出到文件每次排错要敲一堆命令去看日志流第三改代码后重启服务要么kill进程再来一遍要么手动reload非常别扭。Python管理器2.0把这几个痛点全解决了。它直接在面板里帮你管理Python版本、创建独立虚拟环境、配置启动命令还能看到实时的进程日志一行命令不用敲。尤其适合那些“PHP转过来的用户”根本不熟悉Python生态用面板反而比命令行更稳定。免费版就够用不需要买专业版插件别被网上那些诱导升级的帖子带偏。2. 搭建前的环境准备版本选择才是关键2.1 宝塔面板和Python管理器的版本确认动手之前先把环境确认清楚。宝塔面板当前主流是7.9.x和8.x系列Python管理器这个插件在不同版本里叫法有细微差别早期版本叫“Python项目管理器”现在新版叫“Python管理器2.0”在软件商店里搜索“Python”就能找到。安装插件之后需要先装一个Python版本才能创建项目这一步非常关键后面遇到的问题大部分都跟Python版本选择有关。我个人的建议是只装一个Python 3.10.x不要图新鲜去装3.12或3.13。原因很简单Mrdoc基于Django框架Django的LTS版本对Python版本有明确的兼容范围虽然最新Python版本看着性能好但第三方依赖比如MySQLclient、Pillow这些C扩展库的编译兼容性未必跟上来了装的时候容易报错。3.10是当前生态最成熟、兼容面最广的版本几乎不会有坑。注意如果你的服务器系统是CentOS 7尤其要注意Python 3.10编译安装时对gcc版本有要求老系统的gcc默认版本偏低可能在安装Python时出现“cannot find -lpython3.10”这类编译错误。碰到这种问题先升级gcc再装Python不要硬着头皮继续。2.2 项目目录结构和数据库方案的选择很多人在创建项目之前就先把Mrdoc源码下载到服务器了这个顺序其实不对。先从Python管理器2.0里创建项目让面板自动把虚拟环境建好再把Mrdoc源码放到项目目录里。这样虚拟环境和项目路径是统一管理的后续改配置、看日志都方便。目录结构建议这样安排/www/wwwroot/mrdoc # 项目根目录 ├── mrdoc/ # Django项目配置目录settings.py所在目录 ├── app_doc/ # 文档应用目录 ├── manage.py # Django管理脚本 ├── requirements.txt # Python依赖清单 └── venv/ # 虚拟环境目录面板自动生成数据库方面Mrdoc默认使用SQLite这对个人使用和文档站来说完全够用几千篇文章毫无压力。如果你的服务器配置比较高或者未来文档量会非常大也可以用MySQL配合使用。不过强烈建议第一次部署先跑SQLite把整个流程走通了之后再考虑切换MySQL不然一次引入太多变量出问题都不知道从哪里排查。3. 用Python管理器2.0创建虚拟环境别自己手动建venv3.1 Python项目管理器添加项目进入宝塔面板找到Python管理器2.0点击“添加项目”填好项目名称、Python版本、项目路径。这里有一点要注意项目路径填的是Mrdoc源码的根目录而虚拟环境会默认创建在项目路径下的venv文件夹里不需要你手动指定Python解释器路径面板会自动处理好。有一个小技巧刚开始添加项目时可以先随便填一个空目录等面板把虚拟环境建好之后再通过git clone或者文件上传的方式把Mrdoc源码放进去。我踩过一次坑项目路径里已经有文件的情况下面板创建venv反而可能出现权限错乱的问题。空目录创建最干净后续放文件也方便。3.2 把Mrdoc源码放进项目目录Mrdoc的源码托管在Gitee和GitHub上国内服务器优先推荐用Gitee拉取速度比GitHub快一个量级。确认git已经安装然后执行cd /www/wwwroot/mrdoc git clone https://gitee.com/lykops/MrDoc.git .注意命令末尾的“.”这表示把仓库内容克隆到当前目录而不是多套一层MrDoc子目录。如果你的服务器上没有安装git可以用宝塔面板的“终端”功能执行yum install git -yCentOS或apt install git -yDebian/Ubuntu装上。克隆完成后检查一下目录文件是否齐全重点确认manage.py确实在/www/wwwroot/mrdoc下。如果多了一层目录需要把所有文件往上一级拷出来否则后面执行所有命令时路径都不对特别容易混乱。4. 安装依赖和管理配置文件核心环节全拆解4.1 进入虚拟环境并安装Python依赖依赖安装是整个流程里最容易踩坑的环节重点来了。先是进入虚拟环境宝塔的终端默认不会自动激活venv需要手动执行cd /www/wwwroot/mrdoc source venv/bin/activate激活后命令行前缀会显示(venv)字样这表示当前的Python解释器已经切换到了虚拟环境里。执行依赖安装pip install -r requirements.txt这里有几个关键问题要提前说清楚。Mrdoc的requirements.txt里包含lxml、Pillow、diff-match-patch这些带C扩展的库安装时需要有编译环境。CentOS系统如果提示缺少gcc或者相关依赖头文件先补上yum install -y gcc gcc-c python3-devel如果提示这个库是“构建wheel”失败多半就是服务器缺少编译环境不要反复重试pip命令先解决系统依赖。另外如果你想用MySQL而不是SQLite还需要单独安装mysqlclient。这个库对系统库依赖非常敏感CentOS下要先装mysql-develyum install -y mysql-devel如果编译仍然报错可以退一步用PyMySQL做兼容层在Mrdoc的配置文件里改成pymysql.install_as_MySQLdb()就能跑通。但这个属于备选方案新手我建议干脆先用SQLite后端数据库想换可以后期迁移不用上来就给自己挖坑。4.2 修改Mrdoc的核心配置文件Mrdoc的配置文件在mrdoc/config.py老版本可能是Mrdoc/settings.py需要改动的主要是下面几个参数# 安全密钥随便生成一段随机字符串 SECRET_KEY django-insecure-your-random-secret-key-here... # 设置成False正式环境如果开着DEBUG等于裸奔 DEBUG False # 允许访问的域名或IP如果通过域名访问就填域名 ALLOWED_HOSTS [docs.yourdomain.com, localhost, 127.0.0.1] # 如果使用SQLite保持默认即可用MySQL则把下面一段取消注释并填好 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: mrdoc, USER: mrdoc_user, PASSWORD: your_db_password, HOST: 127.0.0.1, PORT: 3306, } }ALLOWED_HOSTS这个是高频报错点。很多人部署完之后访问站点直接报“DisallowedHost”错误就是因为没把自己的域名加进去。如果你是直接用IP访问务必把IP也加进去否则无论如何都会报错。4.3 初始化数据库并创建管理员账号配置改好后执行数据库迁移命令这会把Django自带的用户、权限、会话等数据表以及Mrdoc业务表全部建好python manage.py migrate迁移完成后创建超级管理员账号这个账号就是后续Mrdoc网站的管理员登录账号python manage.py createsuperuser系统会让你依次输入用户名、邮箱和密码。这里有个经验之谈密码别设置太简单Mrdoc后台一旦被爆破整个文档库就全裸奔了最好用带大小写字母和数字的组合。最后收集静态文件这个步骤很多人会漏掉静态文件不收集的话后面访问网站时CSS、JS全部加载不出来页面看起来就像纯文本特别吓人python manage.py collectstatic收集静态文件过程中会提示是否覆盖输入yes确认即可。注意到这里为止所有的命令都是在虚拟环境激活状态下执行的。如果你中途关了终端重新打开后要再执行一次cd /www/wwwroot/mrdoc source venv/bin/activate否则pip和manage.py都会用的系统环境很容易出现“ModuleNotFoundError”之类的诡异报错。5. 配置启动服务并让Nginx反向代理对接5.1 在Python管理器里配置启动命令初始化完成后就可以回到宝塔面板在Python管理器2.0的项目列表里找到创建好的项目点击“配置”或者“启动”。启动方式选择“Gunicorn”这是Django最常用的生产级WSGI服务器并发能力强稳定性也好。启动命令这里不要乱填面板会要求填“启动应用”和“配置端口”。核心是WSGI文件的路径mrdoc.wsgi:application其中前面的mrdoc对应项目目录下mrdoc/wsgi.py文件所在的应用名后面的application是Django默认的WSGI入口对象。应用端口我建议填一个不常用的端口比如8001或者9000不要直接用80因为80端口要留给Nginx监听。配置完成后在项目列表里点击“启动”稍等片刻到进程日志里看到“Listening at: http://127.0.0.1:8001”之类的输出说明服务已经正常跑起来了。5.2 宝塔站点和反向代理的设置Python服务跑起来之后还差最后一步才能从浏览器访问。新建一个站点绑定域名或IP然后在站点的“反向代理”设置里把请求转发到Mrdoc监听的本机端口。比如你的Mrdoc服务跑在127.0.0.1:8001那在宝塔站点里添加反向代理时目标URL填http://127.0.0.1:8001宝塔会自动生成一段Nginx代理配置。这里有个小坑反向代理默认可能会试图把代理URL的路径拼接逻辑处理得过于“激进”如果后续访问文章详情页出现404或路径丢失编辑站点配置文件把代理部分改成系统自动生成的默认规则不要手动加proxy_pass尾部斜杠具体看当前Nginx版本的配置规则。域名解析层面如果你绑定了域名记得先去域名服务商那里加一条A记录把域名指向服务器IP然后在宝塔面板的站点设置里填上对应域名。直接通过IP访问也可以但前提是ALLOWED_HOSTS里填了IP地址否则无法通过Django的域名校验。5.3 HTTPS和TLS安全配置到这一步网站已经能正常访问了但如果你用的是域名建议顺手把SSL证书配上不然后面登录后台时浏览器一直弹“不安全”提示很难受。宝塔面板提供了免费的Let‘s Encrypt证书申请在站点设置里选择“SSL”标签一键申请并开启“强制HTTPS”。这里顺便说个细节很多宝塔面板的老配置默认还开着TLS 1.0/1.1这些老掉牙的加密协议。现代浏览器早就对这些协议说了再见如果发现有些浏览器访问HTTPS站点正常、有些报警或者连不上多半就是TLS版本设置太老。正确的做法是在Nginx配置文件里把SSL协议明确限制为TLSv1.2和TLSv1.3ssl_protocols TLSv1.2 TLSv1.3;这样既保证了兼容性又去掉了不安全的旧加密协议。宝塔在“网站-SSL-配置文件”里能找到Nginx的SSL配置片段把这一行加进去重载Nginx之后所有走老加密协议的请求都会被拒绝安全性提升一个档次。6. 实操中的常见问题与排查技巧实录6.1 访问网站出现DisallowedHost这个算是最常见的新手问题。Django默认只允许白名单里的域名访问如果你直接用IP访问没有在ALLOWED_HOSTS里加入IP页面就会直接报错。处理方法就是我前面说的编辑配置文件把所有可能用到的域名和IP全部放进ALLOWED_HOSTS然后重启服务。6.2 页面能打开但样式全乱JS和CSS全部404这个问题的原因九成是没有执行collectstatic。Django在DEBUGFalse的情况下不会自动托管静态文件必须手动把静态文件收集到STATIC_ROOT目录然后让Nginx直接服务这个目录。如果collectstatic执行过了仍然样式丢失检查一下Nginx站点配置里是否有对项目静态目录的location规则location /static { alias /www/wwwroot/mrdoc/static; }如果没有这一条加上并重载Nginx。6.3 502 Bad Gateway服务挂了还是端口错了502这个状态码在Python项目里基本就等于“Nginx连不上Python进程”。按这个顺序排查问题可能原因排查命令处理方法Python服务未启动面板日志看是否有“Listening at”输出点击项目里的启动按钮端口配错检查反向代理的目标端口改成项目实际的监听端口数据库连接失败看进程日志里是否有MySQL相关报错检查数据库账号密码和网络权限虚拟环境失效手动执行python manage.py check重新进入venv后安装依赖6.4 进程启动后过几分钟就自动挂掉这个坑在低配服务器上特别常见1G内存的机器跑Django有时候就是会内存不足进程直接被系统kill掉。先看看Python项目管理器里是否开启了守护模式确保进程退出后能自动拉起另外排查一下是不是swap交换空间没配置。1G内存的服务器建议开启2G swap这个在宝塔的“终端”里用以下命令操作dd if/dev/zero of/swapfile bs1024 count2048000 mkswap /swapfile swapon /swapfile echo /swapfile swap swap defaults 0 0 /etc/fstab这等于给服务器多加了一部分“应急内存”至少能保证Python进程在并发稍高的时候不至于被秒杀。如果是2G以上的内存机器出现自动挂掉重点查一下是不是系统里跑着别的项目内存被抢光了。6.5 文件上传和图片插入失败Mrdoc的文档编辑支持插入图片图片本质上会上传到服务器本地目录。如果插入图片时报错大概率是上传目录的写权限有问题。在宝塔的文件管理器里把项目根目录下的media文件夹权限改为755所有者改为www用户chown -R www:www /www/wwwroot/mrdoc/media chmod -R 755 /www/wwwroot/mrdoc/media另外文档图片预览有时会走Nginx配置的静态资源别名如果设置了HTTPS但页面里的图片还是http链接多半是因为填写站点域名时没有在Mrdoc后台的“站点配置”里同步更新域名。7. 最后再分享一点我的使用体会Mrdoc部署好之后我自己已经稳定跑了半年多日常记录技术方案、接口文档、服务配置资料全都在上面。访问速度很快MySQL和SQLite模式都实测过个人使用SQLite完全够用而且备份特别简单直接把项目目录打包下载就行。最让我满意的还是文档目录树的设计项目-目录-文档三级结构清晰明了比在语雀里翻文件夹有效率得多。整个流程走下来最耗时间的反而不是部署而是装Python依赖时踩的那些系统编译坑。如果你在部署过程中卡在某个报错上先别急着搜错误码打开宝塔的日志面板看一眼具体报的什么再反推到环境问题思路会清晰很多。另外强烈建议部署完成后一定要顺手开启宝塔的系统防火墙只放行必需的端口SSH、80、443Mrdoc内部的监听端口完全没必要暴露在公网。把HTTPS和密码强度都弄利索之后这套文档系统基本就是省心状态剩下的时间你只需要专注于写文档这件事本身。