Snipe-IT 资产管理系统 Docker 保姆级部署实战：从一台空机器到资产台账上线，一条命令跑通

【免费下载链接】snipe-itA free open source IT asset/license management system项目地址: https://gitcode.com/GitHub_Trending/sn/snipe-it

如果你的公司还靠一张共享 Excel 表格记着几百台笔记本、显示器、软件授权是谁在用，那你大概率经历过这种场面：月底盘点时，财务要设备折旧数据、行政要领用记录、运维要保修状态，而那张表里三分之一的行已经过期了。Snipe-IT 就是来解决这个问题的——一套免费开源的 IT 资产与许可证管理系统（asset/license management system），用 Web 界面管设备、软件授权、耗材、配件和维修记录，还带二维码标签、CSV 批量导入和完备的权限体系。本文用 Docker 把它跑起来，全程可以照抄命令，目标是一台只有 Docker 的空机器，最终得到一个能正常登录、能录资产、能备份恢复的生产可用系统。

本文命令均在 Linux 服务器上验证过，使用的项目版本为当前仓库主分支。文章基于仓库内的docker/docker.env、docker-compose.yml与docker/startup.sh实际配置展开，所有涉及密钥、密码、域名的地方都用占位符标出，请务必替换成你自己的值。

动手之前，先给自己做一次"体检"

大多数部署翻车，不是命令敲错了，而是环境没对齐。照着下面这份清单核对一遍，能省掉后面一半的排障时间。

硬件与系统

软件工具，先确认版本，避免旧版 compose 语法不兼容：

docker --version docker compose version

看到 docker 20+ 和 compose v2 就没问题。接着克隆项目代码（仓库地址仅此一处需要，后续操作全部在本地完成）：

git clone https://gitcode.com/GitHub_Trending/sn/snipe-it cd snipe-it

版本选型说明：docker-compose.yml里应用镜像写的是snipe/snipe-it:${APP_VERSION:-latest}，数据库是mariadb:11.4.7。APP_VERSION没设置时默认拉取latest。想固定版本，就在.env里写死APP_VERSION=v7.x.x——生产环境强烈建议这么做，避免某天latest更新后行为变化。

镜像来源：应用和数据库镜像都从 Docker Hub 拉取，无需额外配置仓库。仓库里docker/目录自带三份 Dockerfile 和一套完整启动脚本（startup.sh），我们不走源码构建，直接用官方镜像最省事。

里程碑一：把配置模板请回家，并逐项"人肉"校对

项目不提供开箱即用的.env，但给了模板，复制一份再改：

cp docker/docker.env .env

打开.env，你会看到大量被注释的键和几个还没被展开的${...}占位符。这里是最容易踩坑的地方：docker/docker.env是给旧版docker-compose.yml（链接方式传数据库地址）用的模板，里面DB_HOST=${MYSQL_PORT_3306_TCP_ADDR}这种写法在新版 compose 里不会被自动展开，原样传给应用容器会导致数据库连不上。我们要做的是把关键项全部改成明确的值。

必须改的配置，一个都不能少：

生成随机密码用系统自带工具即可：

openssl rand -base64 24

至于MAIL_HOST等邮件项，模板里的${MAIL_...}同样不会被展开，可以先全部换成你自己的 SMTP 配置，或者临时注释掉——系统能正常跑，只是收不到通知邮件，后续在后台设置里再补。

里程碑二：生成应用密钥，这是第一条命脉

APP_KEY是 Laravel 应用的加密基石，Snipe-IT 的启动脚本startup.sh里写死了校验逻辑：检测不到APP_KEY就打印提示并退出。生成方式不用自己编，官方镜像里带了 artisan 命令：

docker compose run --rm app php artisan key:generate --show

这条命令会先拉取镜像（第一次较慢），然后输出一串base64:xxxxx。把它填回.env的APP_KEY=后面，格式是APP_KEY=base64:xxxxx，注意base64:前缀别丢。

密钥生成后要长期保存。它用于加密数据库里的敏感字段，换密钥会导致已加密数据无法解密，这不是能随便 rotate 的值。

里程碑三：拉起容器，等一句"Supervisord started successfully"

一切就绪，启动：

docker compose up -d

docker-compose.yml定义了三个东西值得先看懂：app服务把宿主机${APP_PORT:-8000}端口映射到容器内 80；storage卷挂在/var/lib/snipeit（上传文件、备份都在这里）；db服务用mariadb:11.4.7，数据落在db_data卷，还配了 healthcheck，app会等数据库健康后再启动。

看状态：

docker compose ps

两个容器都显示Up之后，盯启动日志：

docker compose logs -f app

日志滚动到最后，看到Supervisord started successfully这行，就说明 Web 服务进程正式接管了。此时按Ctrl+C退出日志跟随（容器不受影响）。

顺带做个快速健康检查——项目在routes/web.php里注册了无需登录的/health路由：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/health

返回200即通过。这一步只验证 Web 层，数据库连接是否正常，等下一步浏览器见真章。

里程碑四：走完 /setup 向导，创建你的第一个管理员

打开浏览器访问http://你的服务器IP:8000。第一次访问没有配置任何用户，系统会自动跳到/setup安装向导。这个向导是 Snipe-IT 独有的初始化流程，分两步：先做环境自检（数据库连通、存储目录可写、.env 是否暴露），再创建管理员账号。

向导里注意三件事：

1. 环境自检页如果报错，会明确告诉你是哪一项不合格，按提示修完刷新即可，不用重来。
2. 管理员账号用你的真实邮箱和强密码，别用admin@example.com / password这种演示值——虽然参考文档常这么写，但这是生产系统，第一步就该正经。
3. 完成后回到登录页，用刚创建的账号登录。登录后第一件事：右上角头像 → 个人资料 → 修改密码（向导里设的只是初始密码）。

登录后进「管理」菜单，把这几项基础数据填上，资产台账才有骨架：

• 厂商管理：录入联想、戴尔等供应商，后续设备型号要引用它
• 资产分类：建"笔记本""显示器""软件"等分类
• 状态标签：配置"可用/在库/维修中/报废"等状态
• 位置：办公室、机房等物理位置

上线之后的三层验证，确认"真的部署成功了"

光能打开登录页不算完，按下面三层走一遍冒烟测试，才算真正交付：

第一层：页面功能冒烟

• 新建一个分类 → 新建一个厂商 → 新建一条资产（不填序列号也能建，但建议填）
• 给资产打二维码标签（列表页的二维码图标），确认图片能正常生成
• 记一条维护记录，确认日期、费用字段能保存

第二层：数据与日志验证

# 应用日志无异常堆栈 docker compose logs app --tail 50 # 数据确实落进了 MySQL（在 db 容器里查一下） docker compose exec db mariadb -u snipeit_user -p snipeit -e "show tables;"

密码会以明文出现在命令行参数里，注意别截图外发。能看到几十张业务表，说明连接和迁移都正常——startup.sh每次启动都会自动执行php artisan migrate --force，所以表结构你不需要手动建。

第三层：重启韧性验证

docker compose restart app

重启后能正常登录、数据还在，说明卷挂载和持久化没问题。这个测试建议在正式交付前必做，它能暴露一大类"数据只存在容器里"的隐患。

把备份、升级、监控排进值班表

部署完成只是起点，运维节奏要固定下来。我给三个建议的固定动作：

备份（每周一次，雷打不动）

Snipe-IT 内置了备份功能，数据会落到storage卷的dumps/目录：

docker compose exec app php artisan backup:run docker compose exec app php artisan backup:list

想备份到宿主机，把卷里的 dumps 目录再拷贝一份出来：

docker cp $(docker compose ps -q app):/var/lib/snipeit/dumps ./backups/

升级（选业务低峰期，半小时内完成）

# 1. 先备份 docker compose exec app php artisan backup:run # 2. 拉新代码（如果用的是 git 部署方式） git pull origin master # 3. 拉新镜像并重启 docker compose pull docker compose up -d # 4. 迁移会自动执行，但可以手动确认 docker compose exec app php artisan migrate --force docker compose exec app php artisan config:clear docker compose exec app php artisan cache:clear

监控（看一眼就够）

docker stats docker compose logs -f --tail 50 app

盯三个指标：CPU 长期 >80% 说明该加资源；/var/lib/snipeit所在磁盘快满就该清备份；日志里出现大量 500 就去看异常堆栈。

踩坑实录：五个高频事故的现象、原因与解药

以下问题都来自真实部署场景，按"现象 → 原因 → 解决"记录。

事故一：容器启动即退出

• 现象：docker compose up -d后docker compose ps显示 app 状态为Exited。
• 原因：APP_KEY缺失。startup.sh检测不到就直接退出，日志里会有Please re-run this container with an environment variable $APP_KEY的提示。
• 解决：按里程碑二生成密钥写入.env，docker compose up -d重新拉起。

事故二：页面 500 或"数据库连接失败"

• 现象：能进/setup但环境自检报数据库错误。
• 原因：.env里DB_HOST还是模板原样DB_HOST=${MYSQL_PORT_3306_TCP_ADDR}，这个变量在 compose 环境下永远不会展开，应用拿它当主机名去连，必然失败。
• 解决：把DB_HOST改成db，DB_PORT改成3306，确保.env里的DB_USERNAME/DB_PASSWORD与 compose 里 db 服务的MYSQL_USER/MYSQL_PASSWORD一致。改完docker compose up -d重建。

事故三：能登录，但上传图片/CSV 报"文件过大"

• 现象：导入 CSV 或上传头像时提示超出upload_max_filesize。
• 原因：PHP 上传上限默认较小。
• 解决：.env里加一行PHP_UPLOAD_LIMIT=100（单位是 MB），startup.sh会在启动时自动写入 php.ini，然后docker compose restart app。

事故四：8000 端口被占

• 现象：docker compose up报端口绑定冲突。
• 原因：服务器上已有别的服务用了 8000。
• 解决：.env里设置APP_PORT=8080（或你喜欢的任意端口），重新docker compose up -d，访问地址随之变化。

事故五：数据"丢了"

• 现象：执行过docker compose down -v后重来一遍，发现所有资产记录都没了。
• 原因：-v会连带删除卷，db_data和storage里的数据一并清空。down不加-v是安全的，加上就是格式化。
• 解决：备份先行；日常重启用restart或down，永远不要对生产数据卷执行down -v。

进阶玩法：缓存、HTTPS、多实例与认证集成

系统稳定跑起来之后，下面几个方向按需取用，点到即止。

Redis 缓存：docker-compose.yml里加一个redis:alpine服务，然后.env配置：

CACHE_DRIVER=redis SESSION_DRIVER=redis QUEUE_CONNECTION=redis REDIS_HOST=redis REDIS_PASSWORD=你的密码

startup.sh已经内置了对REDIS_*环境变量的读取支持，改了就能用。多实例横向扩容的前提就是先上 Redis（否则文件会话在多实例间不共享）。

HTTPS：startup.sh会自动检测/var/lib/snipeit/ssl/snipeit-ssl.crt和snipeit-ssl.key两个文件，存在就启用 Apache 的 SSL 模块。把证书放进 storage 卷的ssl/目录后重启容器即可，无需改任何配置。

多实例：有负载均衡器的话，可以部署多个 app 副本，把APP_PORT错开映射，前置 Nginx 做反向代理。每个副本共享同一个数据库和 Redis，会话由 Redis 统一管理。

认证集成：仓库里已经带了 SCIM 路由（routes/scim.php）、SAML 服务提供者（SamlServiceProvider）和完整的 LDAP 设置项，在后台「设置 → LDAP」里可以配 AD/LDAP 同步，实现公司账号体系单点登录。这个功能建议交给熟悉目录服务的人来配，属于"配置半小时、排障一整天"的典型项目。

CSV 批量导入：仓库sample_csvs/目录下有资产、用户、授权、厂商等各类样例 CSV，后台导入向导会先让你上传文件、再逐字段映射，比手工录几百行高效得多。导入前务必先用assets-sample.csv这种模板格式验证一遍字段名。

收尾：把今天的动作浓缩成一张自检清单

最后照着这份清单过一遍，过了就算正式交付：

• docker compose ps两个容器均为 Up
• curl http://IP:8000/health返回 200
• /setup向导已走完，管理员账号密码已修改
• 已新建至少一条资产并生成了二维码
• .env中APP_KEY、APP_URL、DB_HOST=db均已确认
• php artisan backup:run执行成功，备份文件出现在 dumps 目录
• 重启 app 容器后数据仍在
• 已设置PHP_UPLOAD_LIMIT（如需大文件导入）
• 已用openssl rand生成强密码并妥善保管，未使用示例默认值

到这里，一套能录入资产、能管授权、能追维护、能备份恢复的 Snipe-IT 就已经在你手上跑起来了。接下来值得做的第一件事：把你们公司手头那张共享 Excel 导成 CSV，按sample_csvs/assets-sample.csv的格式整理好，导入系统，让台账真正"活"起来。部署只是开始，数据进去的那一刻，它才开始替你干活。

【免费下载链接】snipe-itA free open source IT asset/license management system项目地址: https://gitcode.com/GitHub_Trending/sn/snipe-it