AssetHub 文档

概述

AssetHub 是一套基于 Laravel 11、Vue 3 和 Tailwind CSS 构建的完整 IT 资产管理系统。它帮助组织跟踪设备生命周期、管理分配、安排维护、计算折旧并生成详细报表。

服务器要求

• PHP 8.2 或更高
• MySQL 5.7+ 或 MariaDB 10.3+
• Composer 2.x
• Node.js 18+ 和 npm 9+
• Web 服务器:Apache 或 Nginx

必需的 PHP 扩展

• OpenSSL, PDO, PDO_MySQL, Mbstring, Tokenizer, XML, Ctype, JSON, GD, Fileinfo

磁盘空间

最低约 200 MB。请为资产照片和文档附件预留额外空间。

安装

方式 A — Web 安装器(推荐)

1. 将项目文件上传到 Web 服务器。
2. 将域名 document root 指向 public/。
3. 设置权限:storage/ 和 bootstrap/cache/ 必须可写(chmod 775)。
4. 将 .env.example 复制为 .env,然后运行 php artisan key:generate。
5. 在浏览器打开 https://yourdomain.com/install。
6. 按向导操作 — Requirements → Database → Migrate → Admin Account → Done。

方式 B — CLI 安装

# 1. 安装依赖
composer install --no-dev --optimize-autoloader
npm install
npm run build

# 2. 配置环境
cp .env.example .env
php artisan key:generate

# 3. 编辑 .env 设置数据库凭据
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. 创建数据库表并播种初始数据
php artisan migrate --seed

# 5. 为上传创建 storage 符号链接
php artisan storage:link

# 6. 为生产缓存配置
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. 标记为已安装
echo "Installed" > storage/installed.lock

Wizard Step 2 — Database Configuration

When the wizard reaches Step 2, you must enter the MySQL connection details for the database you created in your hosting panel. The database must already exist (it can be empty — the next wizard step will create the tables).

Where to find these credentials by hosting panel

• Hostinger: hPanel → Databases → Management → click your database. The page shows name, username, and a "Show password" button.
• cPanel: cPanel → MySQL Databases. The database list shows names; users are listed below. Use "Change Password" if needed.
• Plesk: Plesk → Databases → click the database name. The detail page shows credentials and offers a password reset.
• DirectAdmin: DirectAdmin → MySQL Management → click the database. Credentials and password reset are on the database detail page.
• External / managed DB: AWS RDS, DigitalOcean Managed Database, etc. Use the custom hostname, port (often 3306 but verify), DB name, user, and password from your cloud console. Make sure the server's IP is whitelisted in the DB firewall.

Common errors and how to fix them

本地环境(本地开发)

快速指南:在部署到生产环境之前,在你的电脑上运行 AssetHub 进行测试或开发。选择与你的操作系统匹配的环境。

选项 1 — Laravel Herd(推荐,macOS 与 Windows)

Laravel Herd 是 Laravel 团队的官方本地环境 — 免费、原生、无 Docker。捆绑 PHP 8.2/8.3/8.4、Nginx,以及(Herd Pro 中)MySQL/Redis。

1. 从 herd.laravel.com 下载并安装 Laravel Herd。
2. 将 AssetHub 项目文件夹放入 ~/Herd/(macOS)或 %USERPROFILE%\Herd\(Windows)。Herd 自动创建 .test 域名 — 例如 http://assethub.test。
3. 打开 Herd → Sites 并确认 PHP 版本为 8.2 或 8.3。右键站点 → Secure 启用 HTTPS(QR 扫描器需要)。
4. 创建一个 MySQL 数据库。在 Herd Pro 中使用 Services → MySQL → Open in TablePlus。否则安装 MySQL Community 或使用 SQLite(DB_CONNECTION=sqlite、touch database/database.sqlite)。
5. 将 .env.example 复制为 .env,填入 DB 凭据,然后在项目根目录运行 php artisan key:generate。
6. 在浏览器中打开 http://assethub.test/install 并按照安装向导操作。

选项 2 — XAMPP(Windows、macOS、Linux)

XAMPP 捆绑 Apache、MySQL/MariaDB 和 PHP。免费且跨平台。务必选择 PHP 8.2 或更高的版本。

1. 从 apachefriends.org 下载 XAMPP 8.2+ 并安装。
2. 将 AssetHub 项目复制到 C:\xampp\htdocs\AssetHub\(Windows)或 /Applications/XAMPP/htdocs/AssetHub/(macOS)。
3. 打开 XAMPP Control Panel 并启动 Apache 和 MySQL。如果端口被占用,使用 Config → service.conf 将 Apache 切换到 8080。
4. 前往 http://localhost/phpmyadmin → 新建 → 创建名为 assethub 的数据库,采用 utf8mb4 排序规则。
5. 在项目文件夹中:将 .env.example 复制为 .env,设置 DB_DATABASE=assethub、DB_USERNAME=root、DB_PASSWORD 留空(XAMPP 默认)。运行 php artisan key:generate。
6. 访问 http://localhost/AssetHub/public/install 运行安装向导。

选项 3 — Laragon(Windows)

Laragon 是为 Laravel 设计的便携式 Windows 栈 — 自动 vhost、简洁 URL、MySQL/MariaDB 和内置 HeidiSQL。

1. 从 laragon.org 下载 Laragon Full 并安装。
2. 在 Laragon:菜单 → PHP → Version — 切换到 PHP 8.2 或 8.3。
3. 将 AssetHub 项目复制到 C:\laragon\www\AssetHub\。
4. 点击 Start All。Laragon 自动创建 vhost:http://assethub.test(指向 public/ 文件夹)。
5. 打开 HeidiSQL(内置)→ 创建数据库 assethub。默认凭据:用户 root,密码为空。
6. 用 DB 凭据编辑 .env,运行 php artisan key:generate,然后访问 http://assethub.test/install。

选项 4 — 内置 PHP 服务器(无需 Web 服务器)

最简单的选项:Laravel 自带 artisan serve,可启动开发用 PHP 服务器。不需要 Apache 或 Nginx。最适合快速测试。

# 安装依赖并配置
cd /path/to/AssetHub
composer install
cp .env.example .env
php artisan key:generate

# 运行 migration 并播种初始数据
php artisan migrate --seed

# 启动开发服务器
php artisan serve
# 然后访问: http://127.0.0.1:8000/install

本地环境常见陷阱

QR 扫描器无法在 http:// 上打开摄像头

浏览器摄像头 API 需要 HTTPS,但有一个例外:http://localhost 和 http://127.0.0.1 被视为安全上下文。如果你通过 LAN IP 访问 AssetHub(例如 http://192.168.1.10),摄像头会被拒绝。开发时使用 localhost,或通过 Herd / mkcert 启用 HTTPS。

storage 上的 Permission denied(macOS / Linux)

如果应用尝试写日志或缓存时出现写入错误,修复权限:chmod -R 775 storage bootstrap/cache。Windows 上通常不需要。

端口已被占用

如果端口 8000 被其他应用占用,使用不同端口:

php artisan serve --port=8001

本地测试邮件

在大多数 localhost 设置中,真实 SMTP 不可用。两个安全选项:(1) 在 .env 中设置 MAIL_MAILER=log — 邮件被转储到 storage/logs/laravel.log 而不是发送;或 (2) 使用 Mailtrap / MailHog 将外发邮件捕获到假收件箱。

MAIL_MAILER=log
# 所有邮件都写入 storage/logs/laravel.log

前端资源(Vite / Tailwind)

AssetHub 的 Vue/Tailwind 前端在包中已预构建。如果你编辑 Vue 组件或 Tailwind 配置,需要 Node.js 18+:

npm install
npm run dev    # 开发期间的热重载
npm run build  # 生产构建(部署前运行)

部署到 Hostinger Single(共享主机)

对于没有 VPS 或技术经验的用户,这是推荐路径。AssetHub 与最便宜的 Hostinger Single Web Hosting 套餐(~$2.99/月)完全兼容。无需 SSH、Composer 或命令行 — Single 自带原生 cron jobs、PHP 8.3 和免费 SSL。

步骤 1 — 准备主机

1. 登录 Hostinger hPanel。
2. 前往你的域名的 Hosting → 管理。
3. 通过 高级 → PHP 配置 将 PHP 版本设置为 8.2 或 8.3。
4. 确保启用以下 PHP 扩展(通常默认已启用):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

步骤 2 — 创建 MySQL 数据库

1. 在 hPanel,前往 数据库 → MySQL Databases。
2. 点击 创建新数据库。
3. 记下这 3 个值:
   • 数据库名 — 例如 u123_AssetHub
   • 用户名 — 例如 u123_admin
   • 密码 — 自动生成,请妥善保管

步骤 3 — 上传文件

1. 在 hPanel 前往 文件 → File Manager。
2. 导航到 public_html/(这是你域名的根目录)。
3. 删除该文件夹中任何默认的 index.html 或 default.php。
4. 点击 上传文件,上传整个包中的 source.zip。
   或者你也可以通过 FTP 直接上传 /source/ 文件夹内容。
5. 如果上传的是 ZIP,右键 → 解压。解压后,所有文件应位于 public_html/ 的根目录。
6. 确认 public_html/ 包含:app/、public/、vendor/、.htaccess、index.php(在 public/ 中)、.env 等。

步骤 4 — 运行安装器

1. 打开浏览器访问 https://yourdomain.com/install。
2. 你会看到 AssetHub Installer。
3. 步骤 1:Requirements — 所有检查应通过(绿色)。若有失败,请联系 Hostinger 支持以启用缺失的 PHP 扩展。
4. 步骤 2:Database — 输入上面步骤 2 中的凭据:
   • 主机: localhost
   • 端口: 3306
   • 数据库: u123_AssetHub
   • 用户名: u123_admin
   • 密码:(Hostinger 生成的那个)
5. 步骤 3:Migrate — 点击 "Run Migrations & Seed"。约 10 秒。不要刷新。
6. 步骤 4:Admin — 创建管理员账户。使用强密码。
7. 完成! — 你会看到 Cron URL(请保存!)和登录按钮。

步骤 5 — 通过 Hostinger Cron 配置自动邮件提醒

AssetHub 使用 Laravel 的调度器处理后台任务:保修提醒、维护提醒、文档过期、折旧刷新和逾期 checkout。在 hPanel 设置一个 cron job,Laravel 会决定何时运行哪项任务。

1. 在 hPanel 前往 高级 → Cron Jobs。
2. 点击 创建 Cron job。
3. 选择类型:Custom(不是 "PHP" — 我们需要传参数)。
4. 命令栏输入(将 uXXXXXX 替换为你的 Hostinger 账号用户名):

   /usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

   提示:打开 File Manager,定位 artisan 文件(项目根目录),右键 → 属性以复制完整路径。
5. 将计划设为 每分钟 — 全部五个字段(分、时、日、月、周几)设为 *。
6. 点击 保存。

就这样 — AssetHub 现在会自动发送逾期 checkout 提醒、维护提醒、文档过期提醒、保修提醒,并自动刷新资产折旧值。Laravel 会内部按正确频率(每日 08:00、每月等)调度每项任务。

步骤 6 — 配置邮件(SMTP)

Hostinger 在每个套餐中提供邮箱账户。要用于 AssetHub 通知:

1. 在 hPanel 前往 邮件 → 邮箱账户 并创建一个(例如 noreply@yourdomain.com)。
2. 通过 File Manager 编辑 public_html/ 中的 .env 文件:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. 保存文件。
4. 登录 AssetHub → 设置 → 邮件选项卡 → 发送测试邮件。如果收到,即完成。

Hostinger Single 常见问题

上传后 "500 Internal Server Error"

• 确认 .htaccess 存在于 public_html/ 根目录,并包含重写规则。
• 确认 hPanel 中的 PHP 版本为 8.2 或 8.3。
• 通过 File Manager 检查 storage/logs/laravel.log 查看真正的错误。

上传时 "Permission denied"

Hostinger 通常会设置正确权限,如果没有:

• 在 File Manager 右键 storage/ → 权限 → 递归设为 755。
• 对 bootstrap/cache/ 做同样操作。

二维码扫描器无法打开摄像头

浏览器摄像头 API 需要 HTTPS。Hostinger 通过 Let's Encrypt 提供免费 SSL — 在 hPanel SSL → 管理 中启用。

定时邮件未发送

• 在 hPanel → Cron Jobs → 查看 cron 条目的 Last run 列。如果为空,cron 没在执行 — 检查 artisan 路径是否正确。
• 手动测试命令:在 hPanel 中打开 Terminal(若可用)并运行 cron 命令。如果报错,错误信息会指出问题(PHP 版本错误、路径错误等)。
• 确认 SMTP 配置正确(设置 → 邮件 → 发送测试)。
• 检查 storage/logs/laravel.log 中是否有调度器错误。

性能慢

Hostinger Single 是共享 CPU/RAM。如果团队超过 20 人,考虑:

• 升级到 Premium(~$3.99/月)— 更快的服务器、更多资源、多个数据库。
• 或 Business(~$5.99/月)— 专用资源、每日备份、staging 环境。

配置

.env 文件

应用内设置

大部分非敏感选项可从 管理员 → 设置 配置:

• 常规:公司名/邮箱/电话,asset tag 前缀
• 邮件:发送测试邮件以验证 SMTP
• 通知:保修提醒阈值,维护提醒窗口
• 本地化:时区、日期格式、货币

多语言支持

AssetHub 开箱即用支持 10 种语言,包括 RTL 阿拉伯语。用户通过右上角的国旗下拉菜单切换语言。

内置语言

如何切换语言

1. 点击右上角的国旗图标打开下拉菜单。
2. 从列表中选择您的语言。
3. 页面重新加载;所有 UI 标签、日期和货币格式都会切换。
4. 您的选择同时保存在用户账户和 Cookie(1 年有效期)中。

添加自定义语言(管理员)

管理员 → 设置 → 翻译:

• 点击 "添加 Locale" — 提供代码(例如泰语 th)、显示名称、本地名称、国旗、方向以及要复制翻译的基础语言。
• 在翻译编辑器中内联编辑翻译,或通过 CSV 导入/导出。
• 数据库中的翻译会自动覆盖文件中的翻译。

每个用户的默认语言

每个用户都有 locale 列。得益于 Laravel 的 HasLocalePreference 契约,邮件通知会自动以收件人偏好语言发送。

功能列表

用户与角色

AssetHub 自带 5 个预配置角色:

权限以 Spatie 角色形式存储 — 管理员可通过数据库按权限精细调整。

资产管理

创建资产

1. 导航到 资产 → 新资产。
2. 填写名称、类别、品牌、型号、序列号。
3. 添加购买日期和价格(折旧必填)。
4. 上传图片(支持多文件,每文件最大 5 MB)。
5. 保存 — asset tag 和二维码会自动生成。

Asset Tag 格式

默认:{PREFIX}-{YEAR}-{NNNN},例如 AS-2026-0001。可通过 设置 → 常规 → Asset Tag 前缀 配置。

批量导入

1. 在资产页面点击 导入。
2. 下载 Excel 模板。
3. 填入你的数据 — 必填列:name、category_name。
4. 上传文件。

二维码

每项资产创建时自动获得二维码。二维码编码资产 URL,扫描后直接进入资产详情页。

打印标签

• 单个标签:点击任意资产行的打印机图标。
• PDF 格式:A4,每行 2 个标签,包含 asset tag、名称、品牌、序列号。

扫描

在资产页面点击 扫描二维码。允许摄像头权限。扫描器使用 html5-qrcode,在任何现代浏览器上工作。注意:摄像头访问需要 HTTPS 或 localhost。

工作流

资产分配

1. 打开资产详情页。
2. 点击 分配(资产可用时显示)。
3. 选择用户、可选归还日期、备注。
4. 提交 — 交易创建,邮件通知发送。

资产请求

员工可以提交他们需要的资产请求。请求有 4 种状态:pending → approved → fulfilled,或 rejected。审批邮件自动发送。

Check-in / Check-out

针对共享资产(相机、投影仪、车辆)。预约有日期范围;系统阻止 checkout 重叠。日历视图一目了然显示所有预约。

折旧

AssetHub 使用以下三种方法之一计算资产折旧:

默认值继承自资产的类别。进度条目按月生成。资产的 current_value 在每月 1 日自动更新。

自定义字段

管理员 → 自定义字段让你为资产添加无限自定义属性:

• 类型:文本、数字、日期、选择(下拉)、文本域、文件、复选框
• 范围:适用于所有类别或指定类别
• 重新排序:拖动把手
• 必填字段在保存资产时验证

报表

8 个内置报表,可从报表菜单访问:

1. 资产汇总 — 按状态、状况、类别、部门统计
2. 折旧 — 各类别价值损失,折旧最多的资产
3. 交易 — 一段时间内的分配、归还、转移活动
4. 维护成本 — 按月、类别、类型的支出
5. 保修过期 — 30/60/180 天内需关注的资产
6. 部门资产 — 各部门的资产分布与预算利用率
7. 资产来源 — 在采购、项目、捐赠、转移等来源的分布
8. 库存盘点汇总 — 周期性盘点中的差异

所有报表通过页头按钮支持 Excel 和 PDF 导出。

Webhook

AssetHub 可在关键事件发生时通知外部服务。

可用事件

• asset.created, asset.updated, asset.deleted
• asset.assigned, asset.returned, asset.transferred
• request.created, request.approved, request.rejected, request.fulfilled
• maintenance.scheduled, maintenance.started, maintenance.completed
• checkout.created, checkout.returned

Payload 格式

{
  "event": "asset.assigned",
  "timestamp": "2026-05-05T08:00:00+00:00",
  "data": {
    "asset_id": 1,
    "asset_tag": "AS-2026-0001",
    "asset_name": "HP EliteDesk 800",
    "to_user_id": 4,
    "transaction_id": 12
  }
}

签名验证

如配置了 secret,请求会包含头部 X-AssetHub-Signature,内容为 payload body 的 HMAC-SHA256。在你侧验证:

$expected = hash_hmac('sha256', $rawBody, $secret);
if (hash_equals($expected, $request->header('X-AssetHub-Signature'))) {
  // 有效
}

重试策略

失败投递会以 200 ms 延迟重试 3 次。连续失败 10 次后,webhook 会被自动禁用。

计划任务

AssetHub 使用 Laravel 调度器执行后台 job。你只需一条 cron 条目 — Laravel 会内部在正确时间调度每个 job。

Hostinger / 共享主机(hPanel Cron Jobs UI)

参见 Hostinger 配置 → 步骤 5 一节的截图式说明。简言之:高级 → Cron Jobs → Custom,命令:

/usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

计划:每分钟(五个字段都用 *)。

VPS / 专用服务器(crontab)

以 Web 用户(通常是 www-data)运行 crontab -e,加入:

* * * * * cd /path/to/AssetHub && php artisan schedule:run >> /dev/null 2>&1

备选:外部 URL pinger

如果你的主机完全没有 cron,使用应用内的 Cron URL(设置 → 系统选项卡)配合 cron-job.org(免费,每 15 分钟)。

自动运行的 job

故障排查

storage 上 "Permission denied"

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

二维码扫描器无法打开摄像头

浏览器摄像头 API 需要 HTTPS。安装 SSL 证书,或使用 localhost 测试。

邮件未到达

查看 storage/logs/laravel.log 中的错误。使用 设置 → 邮件 → 发送测试邮件 验证 SMTP 凭据。确保你的 SMTP 服务器允许发送 IP。

重置安装

删除 storage/installed.lock 并再次访问 /install。如果重新运行 migration,现有数据将被擦除。

性能 — 资产列表慢

运行 php artisan optimize 缓存 config、route、view。确保 MySQL 在 assets.asset_tag、assets.serial_number、assets.status 上有索引(migration 已自动创建)。

更新日志

v1.0.0 — 初始发布(2026-05)

• 资产 CRUD,二维码自动生成
• 5 个用户角色(Admin、IT 经理、会计、主管、员工),细粒度权限
• 资产来源跟踪(集中采购、分散采购、投资项目、捐赠、内部转移)
• 分配、归还工作流,邮件通知
• 转移审批工作流(pending → approved/rejected),含权限门控
• 资产请求审批流
• Check-in/check-out 带日历视图
• 维护计划带自动续期
• 文档附件带过期提醒
• 3 种计算方法的折旧 + 寿命终点提醒
• 库存盘点模块 — 周期性盘点带差异跟踪
• 自定义字段,7 种输入类型,拖拽排序
• 8 种报表带图表,Excel 和 PDF 导出(含资产来源、库存盘点汇总)
• 通过 Spatie Activitylog 实现审计日志,带 diff 查看器
• Webhook,HMAC 签名,自动重试
• 多语言 UI:10 种语言(en、vi、es、fr、de、zh、ja、pt-BR、ru、ar 含 RTL)
• 设置 UI:公司、邮件、通知、本地化、翻译
• Web 安装向导
• Emerald-Teal 品牌色板的深色模式

致谢

使用的开源库

• Laravel 11 — MIT
• Vue 3 — MIT
• Inertia.js — MIT
• Tailwind CSS — MIT
• Spatie Permission, Media Library, Activitylog — MIT
• Phosphor Icons — MIT (duotone weight)
• ApexCharts — MIT
• html5-qrcode — Apache 2.0
• Simple QrCode — MIT
• Laravel Excel — MIT
• Laravel DomPDF — MIT