AssetHub 文档

概述

AssetHub 是基于 Laravel 11、Vue 3 和 Tailwind CSS 构建的完整资产管理系统。版本 3.0 在 v2 批次/批量跟踪、分配、报废和公共 QR 交接页面的基础上，新增完整的 Translation Editor、自定义 locale、CSV 导入/导出，以及有效的时区/货币本地化。

服务器要求

• 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 并设置 APP_KEY（如果有 SSH/终端，请运行 php artisan key:generate，或参阅 cPanel 配置 → 步骤 5 了解文件管理器的替代方案）。
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

向导步骤 2 — 数据库配置

当向导进入步骤 2 时，您必须输入在主机面板中创建的数据库的 MySQL 连接信息。数据库必须已存在（可以为空 — 下一步向导将创建表）。

各主机面板中查找凭据的位置

• Hostinger: hPanel → Databases → Management → 点击您的数据库。页面显示名称、用户名及 "Show password" 按钮。
• cPanel: cPanel → MySQL Databases。数据库列表显示名称；用户列在下方。如需重置密码，请使用 "Change Password"。
• Plesk: Plesk → Databases → 点击数据库名称。详情页显示凭据并提供密码重置。
• DirectAdmin: DirectAdmin → MySQL Management → 点击数据库。凭据和密码重置在数据库详情页。
• 外部 / 托管数据库: AWS RDS、DigitalOcean Managed Database 等。使用云控制台中的自定义主机名、端口（通常为 3306，请核实）、数据库名、用户和密码。请确保服务器 IP 已在数据库防火墙白名单中。

常见错误及解决方法

本地环境(本地开发)

快速指南:在部署到生产环境之前,在你的电脑上运行 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 环境。

部署到 cPanel（共享主机）

本指南涵盖标准 cPanel 共享主机（Namecheap、Bluehost、GoDaddy 及大多数经济型主机）。AssetHub 附带预构建的 vendor/ 和前端资源 — 不需要 Composer、npm 或 Web 终端。如果您的 cPanel 缺少终端，请使用 SSH Access 或以下文件管理器解决方案。

步骤 1 — 设置 PHP 版本和扩展

1. 登录 cPanel。
2. 打开 MultiPHP Manager（或 Select PHP Version）并将您的域名设置为 PHP 8.2 或 8.3。
3. 打开 MultiPHP INI Editor 或 PHP Extensions，确认以下扩展已启用：
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo
4. 如果缺少扩展，请在扩展列表中启用或联系主机支持。

步骤 2 — 启用 SSL（HTTPS）

1. 前往 SSL/TLS Status（或 Let's Encrypt SSL / AutoSSL）。
2. 运行 AutoSSL 或为您的域名安装免费证书。
3. HTTPS 是浏览器内置 QR 扫描器访问摄像头的必要条件。

步骤 3 — 创建 MySQL 数据库和用户

1. 打开 Manage My Databases（在数据库下）。
2. 在 Create New Database 下，输入名称（例如 assethub）并点击创建。cPanel 会自动添加账户前缀 — 完整名称形如 cpaneluser_assethub。
3. 在 MySQL Users 下，创建一个强密码的用户。复制带前缀的完整用户名。
4. 在 Add User To Database 下，选择用户和数据库，点击添加，然后授予 ALL PRIVILEGES。此步骤容易遗漏 — 如果没有它，您将收到 Access denied (1045) 错误。
5. 将以下三个值准确记录（与 cPanel 中显示的完全一致）：
   • 数据库名 — 例如 u123_AssetHub
   • 用户名 — 例如 u123_admin
   • 密码 — 自动生成,请妥善保管

步骤 4 — 上传文件

1. 打开 File Manager 并进入 public_html/（您域名的文档根目录）。
2. 启用 Settings → Show Hidden Files 以查看 .htaccess 和 .env。
3. 如有，删除 public_html/ 中任何默认的 index.html。
4. 上传 source.zip 软件包并解压，或通过 FTP 上传 /source/ 文件夹的内容。
5. 解压后，public_html/ 应包含 app/、public/、vendor/、根目录 .htaccess 和同级的 artisan。

步骤 5 — 运行安装程序前准备 .env

在访问 /install 之前完成此步骤。Laravel 要求 .env 中有有效的 APP_KEY 和正确的数据库设置。

1. 在文件管理器中，将 .env.example 复制为 .env（与 artisan 同一文件夹）。
2. 编辑 .env 并至少设置：

   APP_NAME=AssetHub
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=cpaneluser_assethub
   DB_USERNAME=cpaneluser_admin
   DB_PASSWORD="your_password"
   
   SESSION_DRIVER=file
   CACHE_STORE=file

3. 设置 DB_CONNECTION=mysql — 默认 .env.example 使用 SQLite；共享主机需要 MySQL。
4. 在首次迁移前设置 SESSION_DRIVER=file 和 CACHE_STORE=file（避免"找不到 sessions 表"错误）。
5. 如果 DB_PASSWORD 包含特殊字符（#、$、! 等），请用双引号包裹。

生成 APP_KEY（无需终端）

许多 cPanel 方案不包含 Web 终端。请使用以下方法之一：

• SSH Access（cPanel → 安全 → SSH Access）：使用 PuTTY 或 PowerShell 连接，然后运行 cd ~/public_html && php artisan key:generate。
• 文件管理器辅助工具 — 临时创建 public/genkey.php，在浏览器中访问，将输出复制到 APP_KEY=，然后立即删除文件。

  <?php
  echo 'base64:' . base64_encode(random_bytes(32));

• 在您的电脑上 — 如果本地安装了 PHP，运行 php -r "echo 'base64:'.base64_encode(random_bytes(32));" 并将结果粘贴到 .env 中。

• 如果安装程序报告写入错误，请将 storage/ 和 bootstrap/cache/ 权限设置为 755（递归）。

步骤 6 — 运行 Web 安装程序

1. 在浏览器中打开 https://yourdomain.com/install。
2. 步骤 1：Requirements — 所有检查必须通过（绿色）。修复上述步骤 1 中缺少的 PHP 扩展。
3. 步骤 2：Database — 输入步骤 3 中的确切带前缀名称：
   • 主机: 127.0.0.1 or localhost
   • 端口: 3306
   • 数据库: cpaneluser_assethub
   • 用户名: cpaneluser_admin
   • 密码: (your MySQL password)
4. 步骤 3：Migrate — 点击"Run Migrations & Seed"。约需 10 秒。请勿刷新页面。
5. 取消勾选 Include demo data 以进行干净的生产安装。
6. 步骤 4：Admin — 创建您的管理员账户。
7. 完成！ — 保存最终界面显示的 Cron URL。

步骤 7 — 设置 Cron Jobs 以发送邮件提醒

AssetHub 需要每分钟运行一个 cron job，以便 Laravel 可以发送保修提醒、维护提醒和其他定时邮件。

1. 在 cPanel 中，前往 Advanced → Cron Jobs。
2. 在 Add New Cron Job 下，将计划设置为每分钟（* * * * *）。
3. 输入命令（将 CPANELUSER 替换为 General Information 中的 cPanel 用户名）：

   /usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

   提示：PHP 路径可能是 /usr/local/bin/php 或 /usr/bin/php — 如不确定请询问主机。artisan 路径是您上传项目的位置（通常是 /home/CPANELUSER/public_html/artisan）。
4. 点击 Add New Cron Job 保存。

步骤 8 — 配置邮件（SMTP）

创建一个 cPanel 邮件账户用于发送外发通知：

1. 前往 Email Accounts → 创建例如 noreply@yourdomain.com。
2. 在文件管理器中编辑 .env：

   MAIL_MAILER=smtp
   MAIL_HOST=mail.yourdomain.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. 保存，然后在 AssetHub 中：设置 → 邮件 → 发送测试邮件。

cPanel 常见问题

"Access denied for user"（SQLSTATE 1045）

• 准确从 cPanel 复制数据库名称和用户名 — 包括账户前缀。
• 确认您已完成 Add User To Database 并授予 ALL PRIVILEGES。
• 在 cPanel 中重置 MySQL 密码并更新 .env — 如果 DB_PASSWORD 包含特殊字符，请用引号包裹。

数据库步骤通过后迁移失败

• 安装向导测试表单中的凭据，但 Migrate 从 .env 读取。请确保两者一致。
• 如果存在 bootstrap/cache/config.php，请删除后重试。
• 确保 .env 中设置了 DB_CONNECTION=mysql（而非 sqlite）。

迁移期间出现"Invalid default value"（1067）

已在 AssetHub v2.1.0+ 中修复（checkouts 表使用 dateTime 列）。如果您使用旧版本，请更新迁移文件或从 CodeCanyon 下载最新软件包。

上传后出现"500 Internal Server Error"

• 确认根目录 .htaccess 存在且 PHP 为 8.2+。
• 检查 storage/logs/laravel.log 了解真实错误。
• 确认 .env 中已设置 APP_KEY — 空密钥会导致 500 错误。

cPanel 中没有终端

这在许多共享方案上是正常的。请使用 SSH Access（如果已启用）、步骤 5 中的临时 genkey.php 方法，或在本地电脑上生成密钥。

QR 扫描器摄像头无法打开

通过 SSL/TLS Status → AutoSSL 启用 SSL，并通过 https:// 访问网站。

配置

.env 文件

应用内设置

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

• 常规:公司名/邮箱/电话,asset tag 前缀
• 邮件:发送测试邮件以验证 SMTP
• 通知:保修提醒阈值,维护提醒窗口
• 本地化：时区（可搜索列表，含 Europe/Skopje）、日期格式、货币代码（含 MKD — 马其顿代纳尔）、符号及符号位置 — 保存后全应用生效
• 常规 → 公共资产页面：QR 可见性（公开 / 登录 / 禁用），以及 URL 变更后重新生成所有 QR 码
• 本地化 选项卡链接到 Administration → Translations，可打开完整的 Translation Editor（仅管理员）
• Branding：应用名称和 Logo — 更新登录 Logo、页脚、徽章和浏览器页面标题（v4.0+）。登录副标题：在 Administration → Translations 中编辑 auth.login_subtitle
• Appearance（v4.0+）：自定义浅色/深色模式的品牌、状态和文字颜色 — 见 FAQ 中的品牌重塑指南

多语言支持

AssetHub 开箱即用提供 11 种语言，包括 RTL 阿拉伯语和印地语。用户可通过右上角旗帜下拉菜单切换语言。

内置语言

如何切换语言

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

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

前往 Administration → Translations（具有 manage translations 权限的管理员）：

• 点击 "Add Locale" — 提供代码（例如马其顿语 mk）、显示名称、本地名称、旗帜 SVG 文件名、方向（LTR/RTL）以及用于复制翻译的基础 locale。
• 新 locale 将出现在语言切换器和 设置 → 本地化 的默认语言列表中。
• 数据库存储的翻译会自动覆盖 lang/{code}/ 中的文件翻译。

Translation Editor

编辑器按文件（如 assets、nav、settings）分组列出每个翻译键。键显示文件基线和任何数据库覆盖。

• 按 locale、翻译组或搜索文本筛选。
• 点击值进行内联编辑；更改立即保存到数据库。
• 重置键以恢复为文件基线。
• 内置 locale（en、vi、es 等）可编辑；自定义 locale 完全由数据库驱动。
• 仅具有 manage translations 权限的用户可访问此页面。

CSV import / export

• 导出 — 将某 locale 的所有键下载为 CSV（group,key,value）。
• 导入 — 上传相同列的 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. 上传文件。

批次 / 批量资产 (v2)

对于数量相同的同类物品（椅子、键盘、制服），请在新资产表单中选择 跟踪类型 → Batch / Lot，而不是创建重复记录。

1. 输入 数量 和单位（件、套、箱）。保存后，库存归入仓库池。
2. 打开资产 → 分配 选项卡 → 分配 给员工或部门。
3. 使用 归还、调整（损坏/丢失/维修）或处置操作 — 实时汇总必须与总数量对账。
4. 批量资产仅支持 单价；折旧为可选项，默认关闭以加快设置。

二维码

每项资产在创建时自动获得 QR 码。扫描可打开资产的公开或认证页面（见下文）。应用内扫描直接跳转到资产详情页。

打印标签

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

扫描

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

公共 QR 交接页面 (v2)

每项资产还有一个可打印的公共 URL：/a/{asset_tag} — 无需登录即可用于实物交接。

• 在 设置 → 常规 → Public Asset Page 中配置：公开、需要登录或禁用。
• 页面显示照片、关键字段及（对于批次）数量明细。用户可打印为交接单。
• 更改 APP_URL 后，在同一设置面板中点击 Regenerate all QR codes。

工作流

资产分配

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

资产请求

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

Check-in / Check-out

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

报废 — 正式核销 (v2)

磨损或损坏的物品按有文档记录的批次核销，实行职责分离（提议人 ≠ 审批人）。需要 manage disposals 和 approve disposals 权限。

1. 侧边栏 → Disposals → New Disposal。设置标题和期间（Q1–Q4、年度或临时）。
2. 打开草稿 → Add items — 符合条件的损坏批量单位或状况为 Poor 的单项资产。
3. 点击 Submit for approval — 批次锁定。
4. 另一位审批人点击 Approve & execute — 资产/单位标记为已报废。
5. 打印 disposal minutes (PDF) 作为合规记录。

折旧

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

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

自定义字段

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

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

报表

十二种内置报表，可从报表菜单访问：

1. 资产汇总 — 按状态、状况、类别、部门统计
2. 折旧 — 各类别价值损失,折旧最多的资产
3. 交易 — 一段时间内的分配、归还、转移活动
4. 维护成本 — 按月、类别、类型的支出
5. 保修过期 — 30/60/180 天内需关注的资产
6. 部门资产 — 各部门的资产分布与预算利用率
7. 资产来源 — 在采购、项目、捐赠、转移等来源的分布
8. 库存盘点汇总 — 周期性盘点中的差异
9. 员工分配 (v2) — 谁持有哪些资产，包括批量分配
10. 部门 / 位置 (v2) — 按部门或位置统计资产和数量
11. 库存对账 (v2) — 库存 vs 已分配 vs 损坏/丢失/报废
12. 损坏资产 (v2) — 标记为维修或核销的项目

所有报表均支持通过页眉按钮导出 Excel 和 PDF。v2 报表支持数量感知（资产数量 + 总单位数）。

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。

共享主机（cPanel / Hostinger Cron Jobs 界面）

请参阅 cPanel 配置 → 步骤 7 或 Hostinger 配置 → 步骤 5 获取截图说明。简而言之：Advanced → Cron Jobs，命令：

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

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

cPanel Cron 命令

将 CPANELUSER 替换为您的 cPanel 用户名：

/usr/local/bin/php /home/CPANELUSER/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

Upgrade Guides

Step-by-step guides for updating an existing installation. Open the guide that matches your current version.

• v3.1 → v4.0 — Full upgrade guide — Appearance settings, browser tab title from Branding. No migration required.
• v3.0 → v3.1 — Full upgrade guide — Visible languages checklist in navbar picker. No migration required.
• v2.x → v3.0 — Full upgrade guide — Translation Editor, custom locales, localization settings.
• v1.x → v2.0 — Full upgrade guide — Batch assets, disposals, public QR page, operational reports.

故障排查

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。

cPanel 数据库 "Access denied"（1045）

用户名/密码错误、缺少用户到数据库的授权，或密码中的特殊字符导致 .env 解析错误。请参阅 cPanel 配置 → 常见问题。

迁移错误 1067（Invalid default value）

共享主机上的 MySQL 严格模式拒绝多个 NOT NULL timestamp 列。已在 v2.1.0+ 中修复。请更新您的软件包或在 checkouts 迁移中将 checkout_date / expected_return_date 改为 dateTime。

缺少 APP_KEY / 安装前 500 错误

Laravel 要求在应用加载之前 .env 中存在 APP_KEY。如果 cPanel 没有终端，请参阅 cPanel 配置 → 步骤 5 了解 SSH、genkey.php 或本地生成方法。

重置安装

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

性能 — 资产列表慢

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

Upgrading from v3.0.x to v3.1

Download the v3.1 package from CodeCanyon, replace application files (keep your .env and storage/ uploads). No new migrations are required. The new visible_locales setting is optional — if unset, all languages remain visible in the navbar picker.

v3.0 → v3.1 — Full upgrade guide

从 v2.x 升级到 v3.0

从 CodeCanyon 下载 v3 ZIP，替换应用文件（保留 .env 和 storage/ 上传内容），然后运行 php artisan migrate。自定义 locale 和翻译覆盖的新表将自动添加。现有设置和资产将保留。

v2.x → v3.0 — Full upgrade guide

从 v1.x 升级到 v2.0

从 CodeCanyon 下载 v2 ZIP，替换应用文件（保留 .env 和 storage/ 上传内容），然后运行 php artisan migrate。升级不会破坏现有数据 — 现有单项资产继续可用；新的批次/报废表将自动添加。

v1.x → v2.0 — Full upgrade guide

更新日志

v3.1.0 — Visible Language Picker (2026-06)

• Settings → Localization: checklist to choose which languages appear in the navbar language dropdown (built-in + custom locales)
• Default language is always visible; picker auto-hides when only one language is selected
• Backend validates locale switches; users on a hidden locale fall back to the default language
• No database migration required — upgrade is file-replace only
• 登录页品牌：页脚版权和右侧面板徽章跟随 Settings → Branding → App Name（无需改代码）

v3.0.0 — 本地化与 Translation Editor (2026-06)

• Translation Editor 界面位于 Administration → Translations（添加 Locale、内联编辑、按组搜索/筛选）
• 自定义 locale 存储在数据库 — 代码、显示名称、本地名称、旗帜 SVG、方向、基础 locale
• CSV 导入/导出，用于批量更新翻译
• 时区和货币设置现已全应用生效（config/localization.php 含 Europe/Skopje、MKD）
• 设置 → 本地化：可搜索的时区/货币下拉框，支持自定义值
• 新增 Hindi (hi) 为第 11 个内置 locale；Vue 页面遵循 date_format
• 权限控制的 manage translations；数据库覆盖与 lang/ 文件基线合并

v2.0.0 — 运营版本 (2026-06)

• 批次 / 批量资产 — 数量跟踪、分配、归还、实时对账
• 4 个运营报表：员工分配、部门/位置、库存对账、损坏资产
• 报废模块 — 核销批次、职责分离审批、可打印会议纪要 PDF
• 公共 QR 资产页面 /a/{tag}，可见性可配置
• 旧版报表更新为显示资产数量 + 总单位数
• QR 码链接到公共交接页面；交易日志记录批量移动的数量
• 更新演示数据、用户指南（单独包含在 documentation/ 中）及 i18n 字符串

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