水利数字档案馆零基础搭建实操指南：从环境到上线全流程

一、环境准备

必须安装以下指定工具，直接执行对应命令即可：

• Python3.9及以上：Ubuntu系统执行sudo apt update && sudo apt install python3.9 python3.9-venv python3-pip -y；Windows用户从官方地址下载：https://www.python.org/ftp/python/3.9.13/python-3.9.13-amd64.exe，勾选“Add Python to PATH”后安装
• Git：Ubuntu执行sudo apt install git -y；Windows从官网下载：https://git-scm.com/download/win，安装时保持默认选项

二、项目拉取

创建工作目录并拉取官方开源的水利数字档案馆极简分支：

``` mkdir -p ~/water_archives && cd ~/water_archives git clone https://github.com/open-water-archives/water-digital-archive.git . ```

（注：Ubuntu执行需加sudo前缀，Windows在管理员终端操作）

三、虚拟环境与依赖安装

为避免依赖冲突，创建Python虚拟环境并安装项目依赖：

``` Linux/macOS激活虚拟环境 python3.9 -m venv venv && source venv/bin/activate Windows激活虚拟环境 venv\Scripts\activate pip install --upgrade pip pip install -r requirements.txt ```

若依赖安装报错，先执行pip install --upgrade setuptools后重试

四、核心配置修改

1. 数据库配置

找到项目根目录下config/settings.py，修改DATABASES字段为完整内容：

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

必须提前创建MySQL数据库，Ubuntu执行：sudo mysql -u root -p -e "CREATE DATABASE water_archives_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"；Windows在MySQL命令行执行相同语句

2. 媒体路径配置

在settings.py中修改MEDIA相关配置，确保文件存储正常：

```python MEDIA_ROOT = os.path.join(BASE_DIR, 'media') MEDIA_URL = '/media/' ```

创建存储目录：mkdir -p media

五、数据库初始化与数据迁移

虚拟环境激活状态下，依次执行以下命令：

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

执行createsuperuser时，按提示输入用户名、邮箱、密码（密码至少8位，避免特殊字符），此账户用于后台档案管理登录

六、启动服务与验证

执行启动命令：

``` python manage.py runserver 0.0.0.0:8000 ```

必须完成的验证步骤：

• 本地访问：打开浏览器输入http://127.0.0.1:8000，若出现水利数字档案馆首页，前端正常
• 后台登录：输入http://127.0.0.1:8000/admin，用超级管理员账户登录，可看到档案分类、上传模块，后端正常

七、常见问题排查

• MySQL连接失败：检查MySQL是否启动（Ubuntu：sudo systemctl start mysql；Windows：服务中启动MySQL）、配置文件账号密码是否正确、Ubuntu开放3306端口：sudo ufw allow 3306
• 静态资源加载失败：检查settings.py中DEBUG = True（测试环境需设为True）、media目录存在且有权限
• 迁移报错：删除项目根目录下的migrations文件夹，重新执行makemigrations和migrate命令