文书档案系统开发全流程实操指南 从环境搭建到上线零门槛落地

一、前置准备

本教程采用Python+Django轻量技术栈，零开发基础也可直接落地，提前准备以下工具：

• Python3.9+ 下载地址：https://www.python.org/downloads/release/python-3913/，安装时勾选「Add Python to PATH」
• MySQL8.0 下载地址：https://dev.mysql.com/downloads/mysql/8.0.html，安装时设置root账号密码为123456
• VSCode代码编辑器 下载地址：https://code.visualstudio.com/

二、环境搭建

2.1 初始化项目环境

打开cmd/终端，依次执行以下命令：

``` 创建项目文件夹 mkdir document_archive && cd document_archive 创建虚拟环境 python -m venv venv 激活虚拟环境（Windows系统执行） venv\Scripts\activate 激活虚拟环境（Mac/Linux系统执行） source venv/bin/activate 安装项目依赖 pip install django==4.2 pymysql==1.1.0 djangorestframework==3.14.0 ```

2.2 配置数据库连接

首先登录MySQL创建项目数据库：

``` 登录MySQL，输入密码123456即可进入 mysql -u root -p 创建档案系统专属数据库 create database document_archive default charset utf8mb4; exit; ```

执行命令创建Django项目：`django-admin startproject doc_sys .`

打开doc_sys/settings.py文件，修改以下两处配置：

1. 修改ALLOWED_HOSTS允许所有域名访问：

``` ALLOWED_HOSTS = [''] ```

2. 替换默认DATABASES配置为MySQL连接信息：

``` DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'document_archive', 'USER': 'root', 'PASSWORD': '123456', 'HOST': '127.0.0.1', 'PORT': '3306', } } ```

打开doc_sys/__init__.py文件，添加MySQL适配代码：

``` import pymysql pymysql.install_as_MySQLdb() ```

执行数据库初始化命令：

``` python manage.py makemigrations python manage.py migrate 创建后台超级管理员账号，按提示输入账号密码即可 python manage.py createsuperuser ```

三、核心功能开发

3.1 创建档案业务应用

执行命令创建档案专属应用：`python manage.py startapp archive`

打开doc_sys/settings.py，在INSTALLED_APPS列表末尾添加应用：

``` INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'rest_framework', 'archive' ] ```

3.2 编写文书档案数据模型

打开archive/models.py文件，粘贴完整模型代码：

``` from django.db import models from django.contrib.auth.models import User class Document(models.Model): STATUS_CHOICES = ( ('draft', '草稿'), ('published', '已归档'), ('invalid', '已作废'), ) title = models.CharField(max_length=200, verbose_name='档案标题') content = models.TextField(verbose_name='档案内容', blank=True, null=True) file = models.FileField(upload_to='documents/%Y%m/', verbose_name='附件', blank=True, null=True) depart = models.CharField(max_length=100, verbose_name='所属部门') create_user = models.ForeignKey(User, on_delete=models.CASCADE, verbose_name='创建人') create_time = models.DateTimeField(auto_now_add=True, verbose_name='创建时间') update_time = models.DateTimeField(auto_now=True, verbose_name='更新时间') status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='draft', verbose_name='状态') remark = models.TextField(verbose_name='备注', blank=True, null=True) class Meta: verbose_name = '文书档案' verbose_name_plural = verbose_name def __str__(self): return self.title ```

执行命令同步表结构到数据库：

``` python manage.py makemigrations python manage.py migrate ```

3.3 配置后台管理界面

打开archive/admin.py文件，粘贴后台配置代码：

``` from django.contrib import admin from .models import Document @admin.register(Document) class DocumentAdmin(admin.ModelAdmin): list_display = ('title', 'depart', 'create_user', 'create_time', 'status') list_filter = ('status', 'depart', 'create_time') search_fields = ('title', 'content', 'remark') readonly_fields = ('create_user', 'create_time', 'update_time') def save_model(self, request, obj, form, change): if not change: obj.create_user = request.user super().save_model(request, obj, form, change) ```

3.4 配置附件上传规则

在settings.py文件末尾添加以下配置：

``` 附件访问路径 MEDIA_URL = '/media/' 附件存储路径 MEDIA_ROOT = BASE_DIR / 'media' 单文件最大100M DATA_UPLOAD_MAX_MEMORY_SIZE = 104857600 ```

打开doc_sys/urls.py文件，配置路由：

``` from django.contrib import admin from django.urls import path from django.conf import settings from django.conf.urls.static import static urlpatterns = [ path('admin/', admin.site.urls), ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) ```

四、本地功能验证

执行命令启动本地服务：`python manage.py runserver 0.0.0.0:8000`

打开浏览器访问http://127.0.0.1:8000/admin，用之前创建的超级管理员账号登录，即可直接使用档案新增、附件上传、状态修改、部门筛选、关键词搜索等核心功能。

五、Linux服务器上线部署

5.1 服务器基础配置

登录CentOS7+服务器，依次执行命令安装环境：

``` yum install python39 python39-devel mysql-community-server nginx -y 启动MySQL并设置开机自启 systemctl start mysqld && systemctl enable mysqld ```

按照本地数据库配置流程，在服务器MySQL中创建同名数据库、设置root密码为123456。

5.2 项目部署配置

• 将本地项目压缩后上传到服务器/opt/doc_sys目录，解压后按照本地流程创建虚拟环境、安装依赖，额外执行`pip install gunicorn`安装生产环境运行容器
• 新建/etc/systemd/system/doc-sys.service文件，粘贴服务配置：

``` [Unit] Description=Document Archive System After=network.target mysqld.target [Service] User=root WorkingDirectory=/opt/doc_sys ExecStart=/opt/doc_sys/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 doc_sys.wsgi Restart=always [Install] WantedBy=multi-user.target ```

执行命令启动服务：

``` systemctl daemon-reload systemctl start doc-sys systemctl enable doc-sys ```

5.3 Nginx反向代理配置

新建/etc/nginx/conf.d/doc-sys.conf文件，粘贴配置：

``` server { listen 80; server_name 你的服务器公网IP; client_max_body_size 100M; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /media/ { alias /opt/doc_sys/media/; } location /static/ { alias /opt/doc_sys/static/; } } ```

执行`nginx -s reload`重载配置，访问服务器公网IP即可正式使用系统。

六、常见问题排查

• 数据库连接失败：检查MySQL服务是否启动，配置文件密码、数据库名称是否正确
• 附件上传失败：执行`chmod 755 /opt/doc_sys/media`给存储目录赋权限
• 后台样式丢失：执行`python manage.py collectstatic`收集静态资源，确认static目录路径正确