# beikerOAMS

**Repository Path**: tarantella/beikerOAMS

## Basic Information

- **Project Name**: beikerOAMS
- **Description**: 档案从业人员开发的完全开源共享的专业档案管理系统，安装方便、功能齐全、专业，不断迭代演进。
1、档案数据化：档案数据集预训练OCR引擎，自动对档案进行OCR识别。
2、智能交互式档案知识挖掘：支持档案AI智能体交互式知识挖掘和格式化输出。
3、档案数据质检：核查归档文件、归档范围、归档目录之间是否相符。
4、动态专题聚合：按指定规则聚合专题档案，不改变基础档案存储结构。
5、任务调度与行为导引。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 26
- **Forks**: 7
- **Created**: 2024-06-29
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: erp

**Tags**: None

## README

# BeikerOAMS 开源档案管理系统

> Beiker Open-Source Archive Management System
>
> 一套由档案从业人员基于真实业务场景开发的、完全开源的专业档案管理系统。基于 **Laravel 13 + Dcat Admin 2.x** 构建，覆盖档案接收、整理、归档、保管、利用与服务全流程。

## 目录

- [一、项目简介](#一项目简介)
  - [1.1 建设初衷](#11-建设初衷)
  - [1.2 核心特点](#12-核心特点)
  - [1.3 特色功能](#13-特色功能)
- [二、功能模块总览](#二功能模块总览)
  - [2.1 系统管理](#21-系统管理)
  - [2.2 元数据管理](#22-元数据管理)
  - [2.3 档案库](#23-档案库)
  - [2.4 归档数据](#24-归档数据)
  - [2.5 对外服务](#25-对外服务)
  - [2.6 学生档案](#26-学生档案)
  - [2.7 行政管理](#27-行政管理)
  - [2.8 数据作业](#28-数据作业)
  - [2.9 档案作业中心](#29-档案作业中心)
- [三、运行环境](#三运行环境)
  - [3.1 硬件环境](#31-硬件环境)
  - [3.2 软件环境](#32-软件环境)
  - [3.3 PHP 扩展](#33-php-扩展)
  - [3.4 php.ini 建议](#34-phpini-建议)
- [四、部署更新](#四部署更新)
  - [4.1 获取源码](#41-获取源码)
  - [4.2 安装 PHP 依赖](#42-安装-php-依赖)
  - [4.3 配置环境变量](#43-配置环境变量)
  - [4.4 一键初始化（唯一安装入口）](#44-一键初始化唯一安装入口)
  - [4.5 前端资源](#45-前端资源)
  - [4.6 配置 Web 服务器](#46-配置-web-服务器)
  - [4.7 目录权限](#47-目录权限)
  - [4.8 登录系统](#48-登录系统)
  - [4.9 容器化部署说明](#49-容器化部署说明)
  - [4.10 更新总览与入口命令](#410-更新总览与入口命令)
  - [4.11 beiker:db-update](#411-beikerdb-update)
  - [4.12 beiker:admin-sync](#412-beikeradmin-sync)
  - [4.13 宿主机一键脚本 update.sh](#413-宿主机一键脚本-updatesh)
  - [4.14 推荐工作流](#414-推荐工作流)
  - [4.15 注意事项](#415-注意事项)
- [五、许可证](#五许可证)

---

## 一、项目简介

### 1.1 建设初衷

BeikerOAMS（Beiker Open-Source Archive Management System）是由档案从业人员基于实际业务场景开发的开源档案管理系统。旨在解决传统档案管理中**数字化程度低、检索效率差、知识挖掘难、专题管理灵活度不足**等痛点，为企业、机构及个人提供一套专业、易用、可扩展的档案管理解决方案。

系统坚持完全开源共享的理念，持续迭代演进，贴合档案管理的专业规范与实际需求。

### 1.2 核心特点

- **完全开源共享**：MIT 协议，无商业版权限制，支持二次开发与定制化部署，社区共同维护迭代。
- **安装便捷高效**：简化部署流程，降低技术门槛，非专业人员也可快速完成安装配置。
- **功能全面专业**：覆盖档案管理全流程核心需求，符合档案行业规范与实操逻辑。
- **智能高效赋能**：融合 OCR、AI 知识挖掘等技术，提升档案处理与利用效率。
- **灵活扩展兼容**：支持自定义规则与模块开发，适配不同场景下的档案管理需求。

### 1.3 特色功能

1. **档案数据化**：基于档案数据集预训练的 OCR 引擎，自动识别档案中的文本信息，实现纸质档案、扫描件的快速数字化，减少人工录入成本。
2. **智能交互式档案知识挖掘**：构建档案 RAG（Retrieval-Augmented Generation）知识库，通过 AI 智能体支持交互式问答、知识检索与格式化输出，快速挖掘档案中的核心价值信息。
3. **档案数据质检**：自动核查归档文件、归档范围与归档目录的一致性，确保档案数据的完整性、准确性与规范性，降低人工质检误差。
4. **动态专题聚合**：支持按自定义规则（如主题、时间、类型等）聚合专题档案，聚合过程不改变基础档案的存储结构，灵活满足专题化管理与查询需求。
5. **任务调度与行为导引**：提供可视化任务调度功能，支持档案处理流程的自动化触发与跟踪；同时提供操作行为导引，降低系统使用门槛。

---

## 二、功能模块总览

后台菜单按业务域划分为系统管理、元数据管理、档案库、归档数据、对外服务、学生档案、行政管理、数据作业、档案作业中心等板块。

### 2.1 系统管理

集中管理账号、角色、权限、菜单与系统级配置。

| 功能 | 入口 | 说明 |
|------|------|------|
| 用户管理 | `/auth/users` | 后台登录账号；角色通过多选框授予，决定可见菜单与可访问路由 |
| 角色管理 | `/auth/roles` | 角色 = 菜单 + 权限的集合，保存后立即生效 |
| 权限管理 | `/auth/permissions` | 路由级 / 菜单级权限（`slug`、`http_path`、`http_method`） |
| 菜单管理 | `/auth/menu` | 菜单树（标题、图标、`uri`、排序、显隐） |
| 扩展管理 | `/auth/extensions` | 查看 / 启停 Dcat Admin 扩展 |
| 消息中心 | `/gl/notification` | 站内消息与实时推送，支持已读标记与业务跳转 |
| 操作日志 | `/gl/operation-log` | 记录后台写操作（谁、何时、对哪条数据、做了什么） |
| 问卷数据 | `/gl/wjx_push` | 接收并管理「问卷星」推送的问卷数据 |
| 归档表记录 | `/gl/archive-table-record` | 档案数据与目标表 / 字段的映射配置 |
| 归档表字段 | `/gl/archive-table-field` | 源字段 ↔ 目标字段的字段级映射 |
| 归档标准字段 | `/gl/archive-standard-field` | 归档标准字段字典，作为映射标准口径 |
| 归档归档日志 | `/gl/archive-archive-log` | 每次归档的批次、结果、耗时 |
| 参数配置 | `/config-center` | **运行时动态参数**中心：不改代码、不重启即可调整系统行为 |
| 定时与配置总览 | `/da/data-job-schedule` | 汇总展示定时任务与配置项 |
| 操作指导设置 | `/guide-setting` | 为已接入的模型 / 页面绑定操作指导（视频、图片或文字）；未绑定的页面不显示按钮 |
| 测试页 | `/test` | 开发联调用测试页面，生产环境一般不对普通用户开放 |

> **菜单 / 权限 / 角色属于配置数据**：调整后应执行 `php artisan beiker:admin-sync --dump` 固化为权威数据文件，再由部署命令同步到服务器（见 4.13）。

### 2.2 元数据管理

档案业务的基础字典，被档案库、归档等模块引用。

| 功能 | 入口 | 说明 |
|------|------|------|
| 部门 | `/gl/dp` | 组织机构字典（编号、名称、层级），提供部门编码辅助 |
| 归档范围 | `/gl/scope` | 材料是否纳入归档的判定依据 |
| 保管期限 | `/gl/retention` | 永久、30 年、10 年等期限字典 |
| 归档方案 | `/gl/solution` | 归档的分类 / 元数据组合方案 |
| 档案类型 | `/gl/da-type` | 文书 / 科技 / 声像 / 编研 / 捐赠等类型字典 |
| 保密级别 | `/gl/security-level` | 公开、内部、秘密等级别，控制可见性 |

### 2.3 档案库

各门类档案的案卷与卷内文件管理。案卷与卷内文件为一对多关系，支持检索、上传、预览、导出等操作。

| 门类 | 入口 | 说明 |
|------|------|------|
| 声像档案 | `/da/sxda` | 照片、音视频类档案；卷内文件支持上传 / 预览 |
| 文书档案 | `/da/wsda` | 系统最核心的档案库之一；含文件上传、预览、图片 / PDF 遮蔽、分享合成 |
| 科技档案 | `/da/kjda` | 科技档案案卷与卷内文件 |
| 捐赠档案 | `/da/jzda` | 捐赠类档案，可上传捐赠附件 |
| 编研成果 | `/da/by-result` | 汇编、专题研究等编研成果；支持版本快照、素材、引用依据与团队协作 |

### 2.4 归档数据

学生相关的基础归档数据，供其他模块引用。

| 功能 | 入口 | 说明 |
|------|------|------|
| 本科生信息 | `/db/undergrad-info` | 本科生基础信息台账，支持导入导出 |
| 本科生成绩 | `/db/undergrad-score` | 本科生成绩台账，支持按学号、课程筛选与导出 |

### 2.5 对外服务

面向校外 / 校友的业务入口，管理员在后台受理与处理。

| 功能 | 入口 | 说明 |
|------|------|------|
| 综合登记 | `/service/alumni-applies` | 受理校友 / 单位的综合登记申请，含问卷字段映射与材料下载 |
| 查档服务 | `/service/inquiry-zh-center` | 中文学位档案查档等申请的受理、审批与出具，可联动电子签章 |

### 2.6 学生档案

| 功能 | 入口 | 说明 |
|------|------|------|
| 本科毕业档案转递 | `/student/delivery/undergrad` | 转递登记与管理（去向、单号等），支持导出与批量操作 |
| 硕士毕业档案转递 | `/student/delivery/master` | 同上，按硕士批次处理 |
| 博士毕业档案转递 | `/student/delivery/phd` | 同上，按博士批次处理 |
| 学生档案上传 | `/student/assist/file-upload` | 学生自助 / 协助上传档案材料，上传后可预览 |

### 2.7 行政管理

| 功能 | 入口 | 说明 |
|------|------|------|
| 寄递登记 | `/gl/jzdjxx` | 寄递信息登记与维护 |
| 预约管理 | `/gl/reservation` | 到馆 / 业务预约的检索、审核与编辑 |
| 电子签章中心 | `/service/esign-center` | 发起签章、跟踪状态、生成带签章的电子文件 |
| 电子签章核验 | `/service/esign-verify` | 签章文件的验签 / 核验日志 |
| 任务结果 | `/task-results` | 异步 / 后台任务执行结果，支持 JSON 查看与失败重试 |
| 信箱 | `/gl/mailbox` | 处理收件箱邮件，把来信转为业务待办 |
| 快递面单 | `/express` | 面单生成与打印；字段来源、纸张规格、最大 DPI 等可在配置中心调整 |
| 值班管理 | `/duty/*` | 值班记录、计划、策略、成员、基线、换班记录 6 个子功能 |

**值班管理**建议按「成员 / 策略 / 基线 → 值班计划 → 值班记录 / 换班记录」的顺序使用：

| 子功能 | 地址 |
|--------|------|
| 值班记录 | `/duty/daily-record` |
| 值班计划 | `/duty/plan` |
| 值班策略 | `/duty/strategy` |
| 值班成员 | `/duty/member` |
| 值班基线 | `/duty/baseline` |
| 换班记录 | `/duty/swap-record` |

### 2.8 数据作业

按监控点采集文件变更、识别事件、聚合上报，并支持 AI 审批。采集由外部常驻脚本 `scripts/data-job/monitor.py` 执行（支持 inotify / poll / both）。

| 功能 | 入口 | 说明 |
|------|------|------|
| 作业列表 | `/da/data-job` | 作业 = 监控点 + 采集策略；支持启停、暂停、恢复与健康状态查看 |
| 数据作业策略 | `/da/data-job-strategy` | 定义处理 / 判定策略并关联作业 |
| 数据变更记录 | `/da/data-job-event` | 变更事件（created / modified / deleted / renamed / moved，含聚合） |
| 作业明细 | `/da/data-job-item` | 事件下的文件级明细 |
| 智能体审批 | `/da/data-job-approval` | AI 的 `event_judge` / `process` / `acceptance` 结果人工把关 |

### 2.9 档案作业中心

面向「学生馆员 / 综合馆员」的作业辅助。

| 功能 | 入口 | 说明 |
|------|------|------|
| 学生操作记录 | `/stu-op/op-log` | 记录谁、何时、对哪条记录做了什么（可选记录变更前后值） |
| 编辑锁监控 | `/stu-op/edit-lock` | 进入编辑页即加锁，防止多人同时编辑同一条记录；异常 / 超时锁可强制释放 |

**编辑锁机制**：锁在超时（`beiker.stu_op.lock_ttl_minutes`）或关页 / 提交后自动释放；心跳间隔为 `beiker.stu_op.heartbeat_seconds`，总开关为 `beiker.stu_op.enabled`。OCR 文本库等页面的「下一条」导航会依据编辑锁自动跳过已被他人锁定的记录。

---

## 三、运行环境

### 3.1 硬件环境

| 部署场景 | CPU | 内存 | 存储空间 | 网络要求 | 其他外设（可选） |
|----------|-----|------|----------|----------|------------------|
| 个人 / 小型团队（≤5000 份档案） | 双核及以上 | ≥4GB | ≥100GB（含系统 + 档案存储） | 局域网 / 互联网均可 | 扫描仪（纸质档案数字化） |
| 中小型机构（5000–50000 份档案） | 四核及以上 | ≥8GB | ≥500GB（建议 SSD） | 稳定局域网，可选外网访问 | 高速扫描仪、打印机 |
| 大型机构（≥50000 份档案） | 八核及以上 | ≥16GB | ≥2TB（建议分布式存储） | 千兆局域网，支持负载均衡 | 专业扫描设备、备份设备 |

### 3.2 软件环境

| 软件类型 | 版本要求 | 说明 |
|----------|----------|------|
| 操作系统 | Linux（CentOS 7+ / Ubuntu 18.04+）；Windows 10/11 可用于开发 | 生产环境推荐 Linux |
| Web 服务器 | Nginx 1.18+ 或 Apache 2.4+ | 站点根目录必须指向 `public/` |
| PHP | 8.2+（推荐 8.3） | 需启用下述扩展 |
| 数据库 | MySQL 8.0+ | 存储档案元数据、业务数据与账号信息 |
| 缓存 / 队列 | Redis 6.0+ | 建议启用；队列、缓存、广播均依赖 |
| 全文检索 | Elasticsearch 8.x | 档案检索（Laravel Scout） |
| 依赖管理 | Composer 2.0+ | 安装 PHP 依赖 |
| 前端构建（可选） | Node.js 16+ / npm 7+ | 仅在需要重新构建 Vite 资源时使用 |
| 办公文档转换（可选） | LibreOffice / wkhtmltopdf / kkfileview | PDF 生成与在线预览 |

### 3.3 PHP 扩展

必需：`PDO`、`Mbstring`、`Tokenizer`、`XML`、`Ctype`、`JSON`、`Fileinfo`、`GD`、`Iconv`、`OpenSSL`、`SimpleXML`、`SOAP`、`DOM`

推荐 / 业务依赖：`Imagick`（图像处理）、`IMAP`（信箱）、`ZIP`（压缩包处理）

### 3.4 php.ini 建议

```ini
upload_max_filesize = 100M   ; 支持大档案文件上传
post_max_size       = 100M
memory_limit        = 1G     ; 提升 OCR / 批量处理稳定性
max_execution_time  = 300    ; 适配 OCR 识别等耗时操作
```

---

## 四、部署更新

本章分两部分：

- **第一部分：首次安装部署**（4.1 – 4.9）——从源码开始，搭好一套可运行的系统；
- **第二部分：日常更新**（4.10 – 4.15）——服务器 `git pull` 后，用一条命令完成迁移、填充与后台配置同步。

> **免手工搭环境**：运行所需的各类镜像、部署说明与 docker-compose 编排统一放在 [beiker-runtime](https://gitee.com/tarantella/beiker-runtime) 仓库。该仓库正在建设中，内容会持续补充；当前仍可按下文手工部署。

### 4.1 获取源码

```bash
git clone https://gitee.com/tarantella/beikerOAMS.git
cd beikerOAMS
```

### 4.2 安装 PHP 依赖

```bash
# 国内用户可配置阿里云 Composer 镜像（可选）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 生产环境
composer install --no-dev --optimize-autoloader
```

### 4.3 配置环境变量

```bash
cp .env.example .env
```

核心配置项：

```dotenv
# 应用
APP_NAME=BeikerOAMS
APP_ENV=production          # 开发环境填 local
APP_DEBUG=false             # 生产环境务必关闭
APP_KEY=                    # 由 key:generate 自动生成
APP_URL=https://your-domain.example.com

# 数据库
DB_CONNECTION=mysql
DB_HOST=127.0.0.1           # 容器部署时为 mysql
DB_PORT=3306
DB_DATABASE=beiker_oams     # 需提前创建
DB_USERNAME=your_db_user
DB_PASSWORD=

# Redis
REDIS_HOST=127.0.0.1        # 容器部署时为 redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# 队列 / 广播
QUEUE_CONNECTION=redis
BROADCAST_DRIVER=reverb

# 检索
SCOUT_DRIVER=Matchish\ScoutElasticSearch\Engines\ElasticSearchEngine
ELASTICSEARCH_HOST=http://127.0.0.1:9200
```

### 4.4 一键初始化（唯一安装入口）

`composer install` 只负责安装依赖，**不会**自动建库或写数据。安装完依赖、配置好 `.env` 后，执行唯一入口命令：

```bash
php artisan beiker:install --force
```

该命令按固定顺序完成全部初始化（幂等，可重复执行）：

1. 环境检查：PHP 版本、扩展、`.env`、目录可写、数据库连接；
2. 缺少 `APP_KEY` 时自动生成；
3. 创建运行目录（`storage`、`bootstrap/cache`、操作指导素材目录等）；
4. 建立 `public/storage` 软链接；
5. 执行数据库迁移；
6. 运行唯一 Seeder `AdminMenusSeeder`（菜单 / 权限 / 角色 / 关联 + 空库默认管理员 `admin / 111111`）；
7. 刷新菜单缓存与配置中心。

常用选项：

```bash
php artisan beiker:install --dry-run     # 只预演，不写文件、不写库
php artisan beiker:install --force       # 非交互环境确认执行
php artisan beiker:install --skip-migrate --skip-seed --force   # 只做环境/目录/缓存
```

> **铁律**：`beiker:install` 是**唯一**的安装初始化入口。以后新增任何初始化内容（目录、发布资源、默认数据、索引等），都追加到 `InstallCommand::steps()`，不要再新增第二个安装命令。
>
> `AdminMenusSeeder` 仍是唯一的菜单 / 权限 / 角色数据源（幂等，空库与已有库都可执行），并负责空库时创建默认管理员；后台调整菜单、权限、角色或关联后，请在开发环境执行 `php artisan beiker:admin-sync --dump` 重新生成并提交该 Seeder。
>
> `beiker:db-update` 只用于**已有数据库的升级**，不要拿它做首次安装。

### 4.5 前端资源

后台界面样式与脚本由 Dcat Admin 提供，仓库已包含 `public/vendor/dcat-admin` 静态资源，**常规部署无需 npm 构建**。

如需调整 Vite 资源（`vite.config.js`、`resources/js`、`resources/css`），请自行初始化 npm 依赖后构建：

```bash
npm install
npm run build
```

### 4.6 配置 Web 服务器

Nginx 示例：

```nginx
server {
    listen 80;
    server_name your-domain.example.com;
    root /path/to/beikerOAMS/public;   # 必须指向 public 目录
    index index.php index.html;

    client_max_body_size 100m;         # 大文件上传

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.env {
        deny all;
    }
}
```

```bash
nginx -t && systemctl restart nginx
```

### 4.7 目录权限

```bash
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# 建立公开文件软链接
php artisan storage:link
```

### 4.8 登录系统

浏览器访问 `APP_URL`，使用初始管理员账号登录：

- 用户名：`admin`
- 初始密码：`111111`

> 首次登录后请**立即修改密码**。账号与角色绑定属于**环境相关数据**，不随部署命令跨环境同步。

### 4.9 容器化部署说明

生产环境采用容器化部署（nginx / php / mysql / elasticsearch / redis / kkfileview）。运行镜像、部署说明与 docker-compose 编排统一维护在：

**<https://gitee.com/tarantella/beiker-runtime>**

> 该仓库正在建设中，镜像清单与编排文件会陆续补充完整。仓库就绪后，按其中的说明即可一键拉起整套环境，无需逐项安装 PHP、数据库与检索服务。

无论使用该仓库还是自行编排，都需注意：

- **`php artisan` 必须在 php 容器内执行**。宿主机 `.env` 中的 `DB_HOST=mysql` 在宿主机不可解析；
- 宿主机更新代码后，优先使用 `scripts/deploy/update.sh`（见 4.13），脚本会自动 `docker exec` 进入 php 容器；
- 清缓存 / 重载 PHP-FPM / 重启 Horizon、Reverb 可执行 `scripts/clear_cache.sh`。

```bash
docker exec -w /var/www/html/beikerOAMS php php artisan <command>
```

---

### 4.10 更新总览与入口命令

首次安装完成后，日常升级走本节。系统为「服务器 `git pull` 后一键更新」提供了完整的部署更新能力，一条命令解决三类问题：

| 数据类别 | 更新策略 | 依据 |
|----------|----------|------|
| 数据库迁移 | **增量**：只跑没跑过的 | Laravel 自带 `migrations` 表 |
| 数据填充（Seeder） | **增量**：只跑没填充过的 | 新增 `seed_records` 表按 Seeder 追踪 |
| 菜单 / 权限 / 角色及其关联 | **每次覆盖同步** | 唯一 Seeder `database/seeders/AdminMenusSeeder.php` |

| 入口 | 运行位置 | 用途 |
|------|----------|------|
| `php artisan beiker:install --force` | php 容器内 | **首次安装唯一入口**：环境检查、目录、APP_KEY、迁移、唯一 Seeder、缓存 |
| `php artisan beiker:db-update` | php 容器内 | 已有数据库的升级主命令：迁移 + 填充 + 菜单权限角色同步 + 缓存刷新 |
| `php artisan beiker:admin-sync` | php 容器内 | 只同步后台配置数据，可导出、可预演 |
| `bash scripts/deploy/update.sh` | 宿主机 | 一键包装脚本，自动进入 php 容器执行 `beiker:db-update` |

> **边界**：首次安装只用 `beiker:install`；已有数据库升级用 `beiker:db-update` / `update.sh`。两者最终都只运行唯一 Seeder `AdminMenusSeeder`。

### 4.11 beiker:db-update

按固定顺序执行四步，任一步失败即中止后续：

1. **增量迁移**：只执行 `migrations` 表中没有记录的迁移；
2. **菜单 / 权限 / 角色覆盖同步**：调用 `beiker:admin-sync`，把后台配置数据同步为代码定义的版本；
3. **增量填充**：逐个执行 `seed_records` 中没有成功记录的 Seeder；
4. **收尾刷新**：刷新后台菜单缓存与配置中心注册表（失败只告警、不阻断）。

```bash
# 预演：只列计划，不写库（推荐先跑）
php artisan beiker:db-update --dry-run

# 交互确认后执行（默认 No）
php artisan beiker:db-update

# 非交互执行（cron / 脚本 / 无人值守必须显式加 --force）
php artisan beiker:db-update --force

# 只做其中一部分
php artisan beiker:db-update --force --skip-migrate
php artisan beiker:db-update --force --skip-seed
php artisan beiker:db-update --force --skip-admin

# 同步时删除数据文件里没有的多余项（有删除语义）
php artisan beiker:db-update --force --prune
```

| 参数 | 默认 | 说明 |
|------|------|------|
| `--dry-run` | 关 | 预演：只统计与报告，不写库 |
| `--force` | 关 | 跳过交互确认；非交互环境必须显式指定 |
| `--prune` | 关 | 删除数据文件中不存在的多余菜单 / 权限 / 角色及其关联 |
| `--skip-migrate` | 关 | 跳过数据库迁移 |
| `--skip-seed` | 关 | 跳过数据填充 |
| `--skip-admin` | 关 | 跳过菜单 / 权限 / 角色覆盖同步 |
| `--lock=600` | 600 | 互斥锁持有时长（秒），防止并发重复执行 |

> 命令带互斥锁；总开关为 `config('beiker.deploy.enabled')`，可在后台「配置中心 → 部署更新」关闭。

### 4.12 beiker:admin-sync

管理员在后台增删改菜单 / 权限 / 角色后，用本命令把改动**固化为可提交的权威数据文件**，再在服务器上应用。

**身份判定**：页面菜单按 `uri`；父级 / 容器菜单按「标题 + 父级」；权限与角色按 `slug`；关联关系按双方身份。

**同步语义**：数据文件有、库里有 → 覆盖；数据文件有、库里没有 → 新增；库里有、数据文件没有 → 默认保留（`--prune` 才删除并连带清理关联）。不处理 `admin_users` 与 `admin_role_users`。

```bash
# 预演：报告 6 个数据段的新增 / 更新 / 未变 / 删除 / 跳过
php artisan beiker:admin-sync --dry-run

# 应用（只增改，不删）
php artisan beiker:admin-sync

# 应用并删除多余项
php artisan beiker:admin-sync --prune

# 反向导出：把当前数据库写回权威数据文件
php artisan beiker:admin-sync --dump
```

| 参数 | 默认 | 说明 |
|------|------|------|
| `--dry-run` | 关 | 预演，不写库 |
| `--prune` | 关 | 删除 AdminMenusSeeder 中不存在的多余项及其关联 |
| `--dump` | 关 | 导出当前数据库到 `database/seeders/AdminMenusSeeder.php` |
| `--lock=300` | 300 | 互斥锁持有时长（秒） |

### 4.13 宿主机一键脚本 update.sh

```bash
# 默认（不带参数）= 预演，不写库
bash scripts/deploy/update.sh

# 真正执行（写库）
bash scripts/deploy/update.sh --force

# 执行并清理多余项
bash scripts/deploy/update.sh --force --prune

# 执行后清缓存 / 重载 PHP-FPM / 重启 Horizon、Reverb
bash scripts/deploy/update.sh --force --clear-cache
```

| 行为 | 说明 |
|------|------|
| 无参数 | 自动追加 `--dry-run`，只预演不写库 |
| 参数透传 | 除 `--clear-cache` 外的参数原样传给 `beiker:db-update` |
| `--clear-cache` | 非预演执行成功后，于容器内运行 `scripts/clear_cache.sh` |
| `PHP_CONTAINER` | 环境变量，PHP 容器名，默认 `php` |
| `APP_CONTAINER_DIR` | 环境变量，容器内应用目录，默认 `/var/www/html/beikerOAMS` |

### 4.14 推荐工作流

**开发环境（调整菜单 / 权限 / 角色）**

1. 在后台把菜单 / 权限 / 角色调整到满意状态；
2. 执行 `php artisan beiker:admin-sync --dump`，重新生成 `database/seeders/AdminMenusSeeder.php`；
3. 提交该 Seeder（连同代码一起 `git push`）。

**服务器（`git pull` 后一键更新）**

1. `git pull` 拉取最新代码；
2. （可选）预演：`bash scripts/deploy/update.sh`；
3. 正式执行：`bash scripts/deploy/update.sh --force`（需代码改动立即生效再加 `--clear-cache`）；
4. 完成：迁移增量执行、Seeder 增量执行、菜单 / 权限 / 角色覆盖为最新版本。

**纯菜单 / 权限 / 角色更新**（不涉及迁移与填充）：

```bash
docker exec -w /var/www/html/beikerOAMS php php artisan beiker:admin-sync
```

### 4.15 注意事项

1. **默认预演、安全第一**：真正写库务必显式 `--force`；
2. **`--prune` 有删除语义**：操作前先 `--dry-run` 查看；
3. **账号不跨环境**：`admin_users` 与 `admin_role_users` 不同步；
4. **填充追踪的取舍**：`beiker.deploy.track_by_hash` 开启时，Seeder 文件内容变化才会再次执行；需「每次都跑」的 Seeder 应加入 `always_seeders`；
5. **迁移 / 填充均为增量**：不会重复迁移、不会重复填充；
6. **缓存**：命令收尾只刷新菜单与配置中心缓存；OPcache / FPM / Horizon / Reverb 需另跑 `scripts/clear_cache.sh`；
7. **必须在容器内跑 artisan**：宿主机无法解析 `DB_HOST=mysql`。

`config/beiker.php` 的 `deploy` 段：

```php
'deploy' => [
    'enabled'       => env('BEIKER_DEPLOY_ENABLED', true),          // 总开关
    'track_by_hash' => (bool) env('BEIKER_DEPLOY_TRACK_BY_HASH', true), // 按文件内容判断是否重跑
    'always_seeders' => [\Database\Seeders\AdminMenusSeeder::class], // 唯一入口，每次覆盖同步
    'exclude_seeders' => [                                           // 不参与自动执行
        \Database\Seeders\DatabaseSeeder::class,
    ],
    'fresh_only_seeders' => [],
    'refresh' => ['enabled' => (bool) env('BEIKER_DEPLOY_REFRESH_ENABLED', true)],
],
```

> 菜单 / 权限 / 角色及其关联统一由 `AdminMenusSeeder` 覆盖同步；该类已幂等，不再区分空库与已有库。

---

## 五、许可证

本项目采用 [MIT License](LICENSE) 开源协议，Copyright (c) 2025 tarantella。

可自由使用、修改、分发与商业应用，请保留版权声明与许可声明。