一套自己手搓的开源村民管理系统,免费下载部署,功能不收费!免费!
- 2026-09-16 16:18:58
# 村民管理系统 V2.4（2026-09 修复版）— 部署安装教程
相关视频可搜索：钢铁意志刘富贵 查看功能详情及文中的部署教程，本公众号回复关键字“村民管理”、“管理系统” 可免费获得下载链接。
> 适用平台：**Windows**（IIS / 宝塔 / phpstudy）与 **Linux**（宝塔 / 命令行 Nginx+PHP-FPM）
> 技术栈：ThinkPHP 6（PHP 8.0+）+ Vue 3（Vite）+ MySQL 5.7/8.0 + Nginx/Apache/IIS
> 本包为**一体化部署成品**：Composer 依赖（vendor）、打印页依赖（vendor-print）、一体化安装 SQL 均已内置，**无需联网安装依赖、无需手动执行 SQL**，浏览器打开即进入安装向导。
---
## 目录
1. [版本更新说明（本次修复内容）](#1-版本更新说明本次修复内容)
2. [部署总览（三步完成）](#2-部署总览三步完成)
3. [环境要求与依赖](#3-环境要求与依赖)
4. [Windows 部署](#4-windows-部署)
5. [Linux 部署](#5-linux-部署)
6. [安装向导使用说明](#6-安装向导使用说明)
7. [权限体系说明（重要）](#7-权限体系说明重要)
8. [部署后安全清单（必做）](#8-部署后安全清单必做)
9. [移动端使用说明](#9-移动端使用说明)
10. [常见问题（FAQ）](#10-常见问题faq)
11. [附录：伪静态规则](#11-附录伪静态规则)
---
## 1. 版本更新说明（本次修复内容）
本包在 V2.4 基础上完成了**系统性排查与修复**，核心变化如下：
**打印功能修复与增强**
- 打印页支持 `ids` 批量参数：健康/土地列表勾选后可跨页批量打印（修复"缺少打印参数"断链）；
- 健康档案打印：AES 加密的过敏史/慢性病/家族病史解密输出（修复打印乱码），建档医生正确显示；
- 财务流水单打印：科目列正确显示（join 科目表）、合计正确；
-**村民档案打印增强**：单选打印输出完整档案（录入界面全部字段 + 照片）；勾选多行弹出"打印设置"窗口，可自选需要打印的字段（如仅姓名/身份证/手机号），只打印勾选内容；
-**打印脱敏（按权限自动）**：管理员、村支书打印显示完整信息；其他角色（村医/财务/普通用户等）打印自动脱敏——身份证、出生日期、地址打码并标注"已脱敏"，防止敏感信息泄露；
- PDF 导出临时文件自动清理、财务 PDF 收支口径参数透传。
**业务闭环增强**
- 综合治理事件：状态统一（0待处理/1处理中/2已处理/3已完结），新增"完结"操作，填写完结详情完成闭环；
- 走访记录：新增"完结"操作与完结记录，跟进状态含"已完结"；
- 机动值班：打印支持**按日期范围**生成逐日值班表并打印。
**权限体系（重要行为变化）**
- 新增后端权限校验中间件 `PermCheck`：**村民档案 / 健康档案 / 财务管理 / 土地管理** 的写操作（新增/编辑/删除/导入/导出）按模块权限校验；
-**系统管理**（用户/角色/字典/配置/日志/数据健康/备份）仅限管理员（`super_admin` / `admin`）角色；
- 死亡/迁出登记：仅 **管理员 / 村支书 / 村医 / 村书记**（死亡）、**管理员 / 村支书**（迁出）可提交；
- 侧边菜单与页面按钮按登录角色权限显隐，直接访问无权限页面会被拦截。
- 角色权限在「系统管理 → 角色管理 → 分配权限」中配置；详见 [第 7 章](#7-权限体系说明重要)。
**安全加固**
- JWT 密钥支持环境变量 `JWT_SECRET` 覆盖（建议部署时设置轮换密钥）；
- 登录失败锁定（连续 5 次失败锁定 30 分钟，防暴力破解）；
- 文件下载接口路径穿越防护、上传文件 MIME 内容校验、`.sql` 文件禁止 Web 直接下载；
- 操作日志不再记录明文密码；公开接口不再泄露服务器/PHP 版本信息；
- 投票防重复（按登录账号唯一索引原子防重）、分享功能下线；
- 生产环境调试输出已关闭（`debug=false`）。
**功能修复与新增**
- 死亡/迁出「驳回」不再报错（审批意见正确落库）；
- 财务/事件/调解/村务/通知等模块搜索不再 500，字段显示对齐；
- 土地模块地址/承包合同/流转字段前后端对齐（保存与显示正常），新增地块/承包合同自动生成编号；
- 值班排班「沿用上月」不再重复复制；新增/编辑校验与状态机完善；
-**一户一档 360°**：成员详情显示完整省市区 + 详细地址（自动解析区划代码）、居住类型、性别年龄；
-**数据库备份**：修复宝塔环境 `proc_open` 禁用导致备份失败的问题（改用 exec），备份/导入还原验证正常；
-**自动归档**：删除村民时按配置将照片自动归档到指定目录（按命名格式）；
-**基础设置**：村庄信息仅展示安装注册时内容（不可修改）；备份文件列表布局优化；
- 演示数据：`database/demo_data.sql`（可选导入，让新装看板立即有数据）。
---
## 2. 部署总览（三步完成）
```
① 准备环境：Web 服务器 + PHP 8.0+ + MySQL（各平台安装方法见第 4/5 章）
② 解压本包到服务器，站点运行目录指向包内 public\
③ 浏览器访问 http://你的IP或域名/ → 自动跳转安装向导 /install/ → 按提示完成
```
安装向导会自动完成：**依赖检测**（不满足时直接显示对应平台的修复教程）→ **创建数据库并导入一体化 SQL** → **写入数据库连接配置** → **创建管理员**。
---
## 3. 环境要求与依赖
### 3.1 服务器配置
| 项目 | 最低配置 | 推荐配置 |
|------|---------|---------|
| CPU / 内存 | 1 核 2 GB | 2 核 4 GB |
| 操作系统 | Windows 10+ / Server 2016+；CentOS 7+ / Ubuntu 20+ / Debian 10+ | 同左 |
| Web 服务器 | IIS（需 URL Rewrite）/ Nginx / Apache 任一 | Nginx |
| PHP | 8.0+（推荐 8.1 / 8.2） | 8.2 |
| MySQL | 5.7+（推荐 8.0） | 8.0 |
### 3.2 PHP 必需扩展
| 扩展 | 必须 | 用途 |
|------|-----|------|
| pdo_mysql | ✅ | 数据库连接 |
| mbstring | ✅ | 中文处理（姓名/地址/身份证） |
| openssl | ✅ | JWT 鉴权 + AES 加密 |
| ctype | ✅ | 身份证校验 |
| json | ✅ | API 序列化 |
| session | ✅ | 登录状态 |
| fileinfo | ✅ | 上传文件校验 |
| zip | ✅ | Excel 导入/导出 |
| gd | 推荐 | 验证码输出 |
> 💡 **无需手动排查**：安装向导第一步会自动检测上述依赖，缺哪项就显示哪项的修复教程（自动适配 Windows 宝塔 / phpstudy / Linux 宝塔 / apt 等安装方式）。
### 3.3 禁用函数注意
PHP 的 `disabled_functions` 中**不要禁用 `putenv`**（ThinkPHP 6 核心依赖），否则框架无法启动。
---
## 4. Windows 部署
### 4.1 IIS 部署（原生）
1.**安装 IIS**：控制面板 → 启用或关闭 Windows 功能 → 勾选「Internet Information Services」（含"应用程序开发功能 → CGI"）。
2.**安装 URL Rewrite 模块**（必需，用于伪静态）：https://www.iis.net/downloads/microsoft/url-rewrite
3.**安装 PHP 8.1/8.2**（三选一）：
- 官方 PHP（windows.php.net 下载 Non Thread Safe 版，解压后配置 php.ini 启用扩展）；
- phpstudy / 小皮面板一键安装（推荐新手）；
- 宝塔 Windows 版一键安装。
4.**IIS 配置 PHP**：处理程序映射 → 添加模块映射：请求路径 `*.php`，模块 `FastCgiModule`，可执行文件指向 `php-cgi.exe`。
5.**部署文件**：将本包解压到如 `D:\wwwroot\villager-erp\`。
6.**新建站点**：物理路径指向 **`D:\wwwroot\villager-erp\public`**（注意是 public 子目录），端口自定（如 9595）。
7.**权限**：给 `D:\wwwroot\villager-erp\runtime`、`D:\wwwroot\villager-erp\config`、`public\uploads` 添加 IIS_IUSRS 写入权限（config 用于安装向导写数据库配置）。
8.**访问安装**：浏览器打开 `http://127.0.0.1:9595/` → 自动跳转 `/install/` → 完成安装。
>`public\web.config` 已内置全部重写规则（API 转发 + SPA 回落 + `.sql` 禁止下载），无需手工配置伪静态。
### 4.2 宝塔 Windows 部署
1. 安装宝塔 Windows 版（https://www.bt.cn/new/download.html）。
2. 软件商店安装：Nginx + PHP 8.1/8.2 + MySQL。
3. 解压本包到 `C:\BtSoft\wwwroot\villager-erp\`。
4. 网站 → 添加站点：域名/IP 端口自定，**根目录选 `C:\BtSoft\wwwroot\villager-erp\public`**。
5. 设置 → 网站目录 → 运行目录选 `/public`；伪静态选 `thinkphp` 模板。
6. 浏览器访问站点 → 自动进入 `/install/` 安装向导。
### 4.3 phpstudy（小皮面板）部署
1. 安装 phpstudy：https://www.xp.cn/ ，安装 PHP 8.1/8.2 + MySQL + Nginx。
2. 解压本包到 `D:\phpstudy_pro\WWW\villager-erp\`。
3. 网站 → 创建网站：**根目录指向 `D:\phpstudy_pro\WWW\villager-erp\public`**。
4. 伪静态选择 `thinkphp`。
5. 浏览器访问站点 → 完成安装向导。
---
## 5. Linux 部署
### 5.1 宝塔 Linux 部署（推荐，全新安装标准流程）
```bash
# 安装宝塔（CentOS / Ubuntu 通用）
wget -Oinstall.shhttps://download.bt.cn/install/install_6.0.sh && bash install.shed8484bec
```
1. 登录宝塔面板 → 软件商店安装：**Nginx + PHP 8.1/8.2 + MySQL 5.7/8.0**。
2. PHP 设置 → 安装扩展：勾选 `fileinfo`、`zip`（其余默认已装）；禁用函数中移除 `putenv`。
3. 上传本包（`部署源码` 文件夹，可压缩为 zip 后上传）并解压到 `/www/wwwroot/villager-erp/`，解压后站点根下应直接看到 `public`、`application`、`config`、`vendor`、`database`、`runtime` 等目录。
4. 网站 → 添加站点：域名/IP 自定，**根目录填 `/www/wwwroot/villager-erp/public`**。
5. 设置 → 网站目录 → 运行目录选 `/public`；伪静态 → 选 `thinkphp`。
6. 终端设置目录权限（config 需可写，安装向导会写入数据库配置）：
```bash
chmod -R755/www/wwwroot/villager-erp/runtime
chmod -R755/www/wwwroot/villager-erp/public/uploads
chmod -R755/www/wwwroot/villager-erp/config
chown -Rwww:www/www/wwwroot/villager-erp/runtime
chown -Rwww:www/www/wwwroot/villager-erp/public/uploads
chown -Rwww:www/www/wwwroot/villager-erp/config
```
7. 浏览器访问站点 → 自动进入 `/install/` 安装向导 → 按 5 步完成（环境检测 → 数据库 → 站点信息 → 管理员 → 完成）。
8. 安装完成后执行 [第 8 章安全清单](#8-部署后安全清单必做)。
>**数据库准备（可选）**：也可先在宝塔「数据库」中手动创建数据库（utf8mb4），安装向导第②步填写库名/账号/密码即可自动导入全部 42 张表，无需手动执行 SQL。
### 5.2 命令行部署（Ubuntu/Debian + Nginx + PHP-FPM）
```bash
# 1. 安装软件
sudo aptupdate
sudo aptinstall-ynginxmysql-serverphp8.1-fpm \
php8.1-mysql php8.1-mbstring php8.1-xml php8.1-curl \
php8.1-zipphp8.1-gd
# （Ubuntu 22.04 默认源即 PHP 8.1；其他系统将 8.1 换成可用版本号，如 8.2）
# 2. 解压部署
sudo mkdir-p/var/www/villager-erp
sudo unzip部署源码.zip-d/var/www/villager-erp
# 3. 目录权限
sudo chown-Rwww-data:www-data/var/www/villager-erp
sudo chmod-R755/var/www/villager-erp/runtime/var/www/villager-erp/config/var/www/villager-erp/public/uploads
# 4. Nginx 站点配置 /etc/nginx/sites-available/villager-erp
server {
listen 80;
server_name 你的域名或IP;
root /var/www/villager-erp/public;
index index.phpindex.html;
location /{
try_files $uri $uri//index.php?s=$uri;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
}
# 禁止 Web 直接下载 SQL 安装文件（表结构/演示数据）
location ~* \.sql$ {denyall; }
location ~/\. {denyall; }
}
# 5. 启用站点
sudo ln-s/etc/nginx/sites-available/villager-erp/etc/nginx/sites-enabled/
sudo nginx-t && sudo systemctlreloadnginx
```
6. 浏览器访问 → 自动进入 `/install/` 安装向导。
> Apache 用户：包内 `public\.htaccess` 已内置重写规则与 `.sql` 下载防护，站点 DocumentRoot 指向 `public` 并开启 `AllowOverride All` 即可。
---
## 6. 安装向导使用说明
访问站点根目录时，若检测到未安装（无 `config\installed.lock`），会自动 **302 跳转到 `/install/`**，共 5 步：
| 步骤 | 内容 | 说明 |
|------|------|------|
| ① 环境检测 | PHP 版本、必需扩展、目录可写性 | 检测不通过的项目下方**直接显示该平台的修复教程**（如 Windows 宝塔怎么装 zip 扩展、Linux 怎么 apt 安装），修复后刷新重检 |
| ② 数据库 | 主机/端口/库名/账号/密码 | 数据库不存在时自动创建（utf8mb4）；勾选导入则执行一体化 SQL `public\sql\villager_full_v2.9.sql`（全量 42 张表 + 省市区数据，一步到位，无需再执行任何升级脚本） |
| ③ 站点信息 | 乡村名称 + 所在省市区 | 写入站点配置与村庄注册地，村民建档时现居地址省市区级联使用 |
| ④ 管理员 | 账号/密码 | 创建首个管理员（bcrypt 加密，具备全部权限） |
| ⑤ 完成 | — | 写入 `config\installed.lock`，自动进入系统登录页 |
**注意事项**：
- 安装完成后 `config\database.php` 由向导自动写入（已内置关闭调试输出），一般无需手动改。
- 重新安装：删除 `config\installed.lock` 后再次访问站点即可（数据库已存在时向导会复用，不重复建库）。
- 一体化 SQL 含 `DROP TABLE IF EXISTS`，**请勿在已有业务数据的库上重复导入**。
- 若数据库账号无建库权限：先在宝塔「数据库」中手动创建数据库并授权，再在向导中填写（向导支持直接使用已存在的库）。
---
## 7. 权限体系说明（重要）
本版加强了后端权限校验，**角色权限决定能操作哪些模块**：
| 模块 | 可写角色（默认种子权限） | 说明 |
|------|------------------------|------|
| 村民档案 / 健康档案 / 财务 / 土地 | `super_admin`、`admin`（含模块通配权限的角色） | 写操作（新增/编辑/删除/导入/导出）需对应模块权限 |
| 死亡登记 | 管理员 / 村支书 / 村医 / 村书记 | 提交后需审批（管理员/村支书/村医可审批） |
| 迁出登记 | 管理员 / 村支书 | 提交后需审批（管理员/村支书可审批） |
| 系统管理（用户/角色/字典/配置/日志/数据健康/备份） | 仅 `super_admin`、`admin` | 普通角色不可进入 |
| 走访 / 值班 / 综治 / 党群 / 乡村 | 登录用户（按角色权限显示） | 协作类功能，读操作对登录用户开放 |
- 分配权限：**系统管理 → 角色管理 → 分配权限**（勾选模块与操作码）。
- 若某账号登录后提示"无权限执行该操作"，说明该角色未分配对应模块写权限，在角色管理中为其勾选即可。
- 菜单与页面按钮按权限自动显隐；直接输入无权限的 URL 会被拦截并跳回首页。
---
## 8. 部署后安全清单（必做）
安装完成并验证系统可用后，按顺序执行以下安全加固：
1.**删除安装向导**：删除服务器上的 `public/install/` 目录（防止被重新安装/覆盖配置）。向导第⑤步也会提示。
2.**确认安装锁**：确认 `config/installed.lock` 存在（安装向导会自动创建）。
3.**限制 SQL 下载**：
- Apache/IIS：包内 `.htaccess` / `web.config` 已禁止 `.sql` 直接访问；
-**Nginx（宝塔）**：在站点配置 server 段加入 `location ~* \.sql$ { deny all; }`（或删除 `public/sql/` 目录）。
4.**修改默认口令**：登录后立即修改管理员密码；数据库密码不要与业务默认密码相同。
5.**JWT 密钥**（可选但推荐）：在 PHP 环境变量或宝塔「PHP 设置 → 环境变量」中设置 `JWT_SECRET` 为随机长串（如 `openssl rand -hex 32`），轮换后所有用户需重新登录。同时可设置 `AES_KEY` 环境变量覆盖健康档案加密密钥。
6.**数据库口令独立**：生产环境数据库账号密码使用随机强口令（安装向导填写时即写入配置）。
7.**目录权限收紧**：安装完成后可将 `config/` 权限从 755 收紧为 755 仅写（保持 PHP 可读、系统可写锁文件即可）；`runtime/`、`public/uploads/` 保持可写。
8.**备份**：在「系统管理 → 基础设置 → 备份」中配置站外备份目录并执行一次手动备份验证。
---
## 9. 移动端使用说明
系统内置**设备自动侦测**：用手机/平板浏览器打开站点时自动切换为移动端 UI，功能与电脑端**完全一致**。
| 能力 | 电脑端 | 手机端 |
|------|--------|--------|
| 侧边导航 | 左侧固定栏（可折叠） | 顶部汉堡按钮 → 左侧抽屉滑出 |
| 统计卡片/图表 | 多列栅格 | 自动单列堆叠、图表全宽 |
| 弹窗表单 | 固定宽度居中 | 94% 宽近乎全屏、表单单列、内容可滚动 |
| 数据表格 | 整表显示 | 保持列宽、横向滑动查看 |
| 搜索栏 | 行内多字段 | 两列紧凑排列、按钮整行 |
| 一户一档 360° | 左右两栏 | 上下堆叠（先搜索、后台账） |
侦测规则：手机 UA（Android/iPhone/iPad 等）或窗口宽度 < 768px 即切换；手机浏览器直接访问与电脑同一地址即可，无需任何配置。
---
## 10. 常见问题（FAQ）
**Q1：访问站点显示 500.19 / 无法读取 web.config**
站点物理路径没有指向 `public` 目录（或指向了不存在的路径）。确认站点根目录是 `包解压目录\public`，且该目录存在 `web.config`。
**Q2：访问站点出现 PHP 欢迎页或目录列表**
运行目录未指向 `public`。IIS 将站点物理路径改为 `public`；宝塔在"网站目录 → 运行目录"选择 `/public`。
**Q3：打开后白屏 / 自动跳到 /install/**
说明系统未安装或 `config\installed.lock` 丢失。按向导完成安装即可；如已安装过，检查站点能访问到 `config\installed.lock` 文件。
**Q4：接口 404（前端报"请求错误"）**
伪静态未生效：IIS 检查 URL Rewrite 模块是否安装；Nginx/Apache 检查伪静态是否选 `thinkphp` 模板（或使用第 11 章规则）。
**Q5：安装向导第①步某项检测不通过**
向导会在该项下方显示对应平台的修复教程，按教程操作后点击"重新检测"。
**Q6：数据库导入报错 / 乱码 / `Data too long for column 'code'`**
多为字符集或数据问题。确认建库字符集为 utf8mb4；MySQL 8.0 用户建议直接用安装向导导入（向导自动处理编码）。若报 `1406 Data too long for column 'code'`：说明导入的 SQL 与库内表结构不匹配（通常是在旧版本库上重复导入，或目标库残留旧版同名表）。**解决办法：删除该数据库后重新创建**（`DROP DATABASE 库名; CREATE DATABASE 库名 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`），再重新运行安装向导并勾选导入。本包 SQL 已修复区县数据超长问题（`database/villager_full_v2.9.sql` 与 `public/sql/` 同步）。
**Q7：登录一直提示密码错误**
默认账号为安装向导第④步自己创建的账号。忘记密码可联系管理员在"系统管理 → 用户管理 → 改密"重置。
**Q8：`Driver [file] not supported` 或日志写入失败**
`runtime\` 目录不可写。Windows 给 IIS_IUSRS 写入权限；Linux 执行 `chmod -R 755 runtime && chown -R www:www runtime`。
**Q9：验证码不显示**
PHP 未装 `gd` 扩展，按向导第①步教程安装后重启 PHP。
**Q10：Excel 导入/导出报错**
PHP 未装 `zip` 扩展，按向导第①步教程安装后重启 PHP。
**Q11：手机访问布局错乱/与电脑端一样**
手机端靠前端脚本侦测自动切换，若显示异常：刷新页面（确保加载最新 JS/CSS）；清理浏览器缓存后重试。
**Q12：某账号提示"无权限执行该操作"**
角色未分配对应模块权限。用管理员登录 → 系统管理 → 角色管理 → 分配权限 → 勾选该模块后保存；重新登录生效。
**Q13：批量打印（健康/土地）勾选后打开提示"缺少打印参数"**
部署包内 `public/print.html` 为修复版（支持 ids 批量）。若仍异常，确认该文件为最新（含 `ids.value.length` 逻辑），或清理浏览器缓存。
**Q14：健康档案打印显示乱码**
确认 `public/print.html` 与 `application/app/controller/PrintController.php` 为修复版（打印前对 AES 加密字段解密）。
**Q15：安装完成后访问站点根出现"访问被拒绝 / 403"（无法进入登录页）**
按以下顺序排查：
1.**运行目录**：宝塔「网站 → 设置 → 网站目录 → 运行目录」必须选择 `/public`。若站点根直接是解压目录而未设运行目录，访问 `/` 会因找不到 index 文件被 Nginx 拒绝（403）。正确配置后站点根应能看到 `public/index.php`。
2.**站点根目录**：宝塔添加站点时"根目录"应填解压后的项目根（含 `application`、`config`、`vendor`、`public`），**不是**`public`。
3.**文件权限**：Linux 执行 `chmod -R 755 runtime config public/uploads && chown -R www:www runtime config public/uploads`（config 需可写，安装向导与锁文件依赖）。
4.**安装锁**：确认 `config/installed.lock` 存在（安装向导第④步写入）。若不存在说明安装未真正完成（config 目录不可写导致锁写入失败），重新设置权限后删除 `config/installed.lock` 再次运行 `/install/`。
5. 访问 `http://你的域名/index.php`：若返回"系统启动失败"诊断页，按页面提示处理（数据库配置 / vendor / 权限）。
6. 清理浏览器缓存后重试。
**Q16：再次访问 /install/ 显示"系统已安装"**
安装完成后请删除 `public/install/` 目录。如确需重装：先删除 `config/installed.lock` 再访问 `/install/`（数据库已存在时勾选"导入演示数据"会重建全部表，请先备份）。
---
## 11. 附录：伪静态规则
**Nginx**（宝塔可直接选 `thinkphp` 模板）：
```nginx
location / {
if (!-e $request_filename) {
rewrite ^(.*)$ /index.php?s=$1 last;
break;
}
}
# 安全：禁止下载 SQL 安装文件
location ~* \.sql$ { deny all; }
```
**Apache**（包内 `public\.htaccess` 已内置，含重写与 `.sql` 防护）：
```apache
<IfModule mod_rewrite.c>
Options +FollowSymlinks -Multiviews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php?/$1 [QSA,PT,L]
</IfModule>
