从零搭建开源户籍档案管理系统 全流程可落地实操部署指南

一、前期环境准备

1.1 硬件要求

最低配置：2核4G云服务器/本地主机，硬盘剩余空间≥50G，操作系统支持CentOS7.6+/Windows10+/MacOS12+

1.2 软件依赖安装

所有依赖固定版本，避免兼容性问题，安装后需执行校验命令确认安装成功：

• JDK1.8：下载地址 https://www.oracle.com/cn/java/technologies/downloads/java8-windows，安装后配置环境变量，执行java -version返回1.8.x版本即为成功
• MySQL8.0：下载地址 https://dev.mysql.com/downloads/mysql/8.0.html，安装时设置root密码为household123，创建名为household_registry的空数据库
• Node.js16.20.0：下载地址 https://nodejs.org/download/release/v16.20.0/，安装后执行node -v返回v16.20.0即为成功
• Redis6.2.7：下载地址 https://download.redis.io/releases/redis-6.2.7.tar.gz，启动后执行redis-cli ping返回PONG即为成功

二、系统部署全流程

2.1 源码下载

执行以下命令拉取稳定版源码，或直接访问Gitee地址下载压缩包：

``` git clone https://gitee.com/opensource_community/household-registry-system.git -b v1.0.0 ```

源码分为后端household-admin、前端household-ui两个独立目录。

2.2 数据库初始化

进入源码根目录的sql文件夹，执行以下命令导入初始表结构和基础数据：

``` mysql -uroot -phousehold123 use household_registry; source ./init.sql; ```

必须确保导入无报错，否则后续启动会出现表不存在的问题

2.3 后端配置与启动

进入household-admin/src/main/resources目录，修改application.yml配置文件，完整可复制配置如下：

```yaml server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://127.0.0.1:3306/household_registry?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8 username: root password: household123 redis: host: 127.0.0.1 port: 6379 password: '' 数据自动备份配置 backup: enable: true cron: 0 0 2 ? path: /data/household/backup Windows系统改为D:\\household\\backup max-history: 30 ```

配置完成后，在household-admin根目录执行以下命令启动后端：

``` 本地测试直接启动 mvn spring-boot:run 生产环境打包成jar包后台运行 mvn clean package -DskipTests nohup java -jar target/household-admin-1.0.0.jar & ```

访问http://127.0.0.1:8080/doc.html 出现swagger接口文档即为后端启动成功。

2.4 前端配置与启动

进入household-ui目录，修改.env.development配置文件，将后端接口地址改为自己的后端地址：

``` VUE_APP_BASE_API = 'http://127.0.0.1:8080' ```

执行以下命令启动前端：

``` 安装依赖，用国内镜像加速 npm install --registry=https://registry.npmmirror.com 本地启动 npm run dev 生产环境打包，打包后的文件在dist目录 npm run build:prod ```

启动后访问http://127.0.0.1:80 ，默认管理员账号admin，密码admin123，登录成功即为部署完成。

三、核心功能配置实操

3.1 户籍档案录入规则配置

登录系统后进入【系统设置】-【字段配置】页面，可根据本地户籍管理要求调整字段规则：

• 必填字段设置：勾选姓名、身份证号、户号、户籍地址、联系电话、出生日期字段的「必填」选项，保存后录入档案时未填对应字段无法提交
• 校验规则设置：身份证号字段默认开启18位格式校验，可根据需求添加港澳通行证、台胞证等证件类型的校验规则
• 户号关联设置：开启「同一户号关联家庭成员」选项后，录入同户号人员时会自动关联已录入的家庭成员，无需重复填写户地址等公共信息

3.2 权限分级配置

进入【系统管理】-【角色管理】页面，可配置三类角色权限，避免数据泄露和误操作：

• 管理员：拥有所有权限，包括档案增删改查、用户管理、系统配置，仅分配给户籍管理部门核心负责人
• 录入员：拥有档案录入、修改、查询权限，无删除、导出、系统配置权限，分配给窗口录入人员
• 查询员：仅拥有档案查询、导出权限，无修改删除权限，分配给查询窗口人员

所有角色默认开启操作日志记录，可在【操作日志】页面查看所有人员的档案操作记录，追溯数据修改来源

3.3 数据备份配置

默认配置已经开启每天凌晨2点自动备份，如需调整可直接修改application.yml中的backup段落，重启后端即可生效。手动备份可进入【系统设置】-【备份管理】页面，点击「立即备份」按钮，备份文件会自动存储到配置的路径下。

四、常见问题排查

• 后端启动报错端口被占用：执行lsof -i:8080（Linux/Mac）或netstat -ano | findstr 8080（Windows）找到占用进程的PID，执行kill 进程ID结束进程，或修改application.yml中的server.port为未占用端口
• 前端访问后端接口跨域：检查前端配置的VUE_APP_BASE_API地址是否正确，生产环境建议用Nginx反向代理解决跨域，Nginx配置可直接复制以下内容： ``` location /prod-api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; } ```
• 导入历史档案失败：检查导入的Excel模板是否和系统提供的模板一致，身份证号、户号等必填字段是否为空，格式是否符合要求
• 备份失败：检查配置的备份路径是否有写入权限，Linux系统可执行chmod 777 备份路径赋予写入权限