企业官网建设流程全解析

先说结论：在宝塔面板上用Python管理器2.0装Mrdoc，是自建在线文档系统里最省心的一条路。Mrdoc这东西对个人开发者太友好了，纯开源、支持Markdown语法、自带目录和全文搜索，部署在自己服务器上数据完全可控，不用怕第三方知识库哪天停服或者审核抽风。而宝塔的Python管理器2.0，正好把原来那套“SSH进去建虚拟环境、pip装依赖、手写systemd守护进程”的流程全部可视化，环境隔离、日志查看、进程守护都能在面板里点鼠标搞定。这篇文章我直接把完整实操流程和踩过的坑都写出来，适合用过宝塔但没怎么碰过Django项目的人，照着走就能把Mrdoc跑起来。

1. 为什么我用Python管理器2.0来跑Mrdoc

1.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创建虚拟环境，别自己手动建venv

3.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 -y（CentOS）或apt install git -y（Debian/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-devel：

yum 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.3：

ssl_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在DEBUG=False的情况下不会自动托管静态文件，必须手动把静态文件收集到STATIC_ROOT目录，然后让Nginx直接服务这个目录。如果collectstatic执行过了仍然样式丢失，检查一下Nginx站点配置里是否有对项目静态目录的location规则：

location /static { alias /www/wwwroot/mrdoc/static; }

如果没有这一条，加上并重载Nginx。

6.3 502 Bad Gateway，服务挂了还是端口错了

502这个状态码在Python项目里基本就等于“Nginx连不上Python进程”。按这个顺序排查：

6.4 进程启动后过几分钟就自动挂掉

这个坑在低配服务器上特别常见，1G内存的机器跑Django有时候就是会内存不足，进程直接被系统kill掉。先看看Python项目管理器里是否开启了守护模式，确保进程退出后能自动拉起，另外排查一下是不是swap交换空间没配置。1G内存的服务器建议开启2G swap，这个在宝塔的“终端”里用以下命令操作：

dd if=/dev/zero of=/swapfile bs=1024 count=2048000 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、443），Mrdoc内部的监听端口完全没必要暴露在公网。把HTTPS和密码强度都弄利索之后，这套文档系统基本就是省心状态，剩下的时间你只需要专注于写文档这件事本身。