Snipe-IT 资产管理系统 Docker 保姆级部署实战：从一台空机器到资产台账上线，一条命令跑通
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实际配置展开，所有涉及密钥、密码、域名的地方都用占位符标出，请务必替换成你自己的值。
动手之前，先给自己做一次"体检"
大多数部署翻车，不是命令敲错了，而是环境没对齐。照着下面这份清单核对一遍，能省掉后面一半的排障时间。
硬件与系统
| 检查项 | 最低要求 | 我的建议 |
|---|---|---|
| 操作系统 | 任意支持 Docker 的 Linux 发行版 | Ubuntu 22.04 / Debian 12 均可 |
| 内存 | 2 GB | 4 GB 以上，跑 MySQL 更从容 |
| 磁盘 | 10 GB 可用 | 单独给数据卷留足空间 |
| 端口 | 8000（可改） | 生产环境建议换高位端口 |
软件工具，先确认版本，避免旧版 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 里不会被自动展开，原样传给应用容器会导致数据库连不上。我们要做的是把关键项全部改成明确的值。
必须改的配置，一个都不能少：
| 配置项 | 填什么 | 说明与注意 |
|---|---|---|
APP_KEY= | base64:...（下一步生成） | 应用加密密钥，留空容器直接启动失败 |
APP_URL= | http://你的服务器IP:8000 | 生成邮件链接、二维码依赖它 |
APP_TIMEZONE= | Asia/Shanghai | 时区，决定所有时间显示 |
APP_LOCALE= | zh或en | 界面语言 |
DB_HOST= | db | 改成 compose 服务名，不要留模板的${...} |
DB_PORT= | 3306 | |
DB_DATABASE= | snipeit | 数据库名 |
DB_USERNAME= | snipeit_user | 普通账号 |
DB_PASSWORD= | 一串强随机密码 | 别和 root 密码相同 |
MYSQL_ROOT_PASSWORD= | 另一串强随机密码 | compose 文件里 db 服务会读取这个值 |
MAIL_MAILER= | smtp | 邮件可后配，不影响部署 |
生成随机密码用系统自带工具即可：
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 -ddocker-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 是否暴露），再创建管理员账号。
向导里注意三件事：
- 环境自检页如果报错，会明确告诉你是哪一项不合格，按提示修完刷新即可，不用重来。
- 管理员账号用你的真实邮箱和强密码，别用
admin@example.com / password这种演示值——虽然参考文档常这么写，但这是生产系统，第一步就该正经。 - 完成后回到登录页，用刚创建的账号登录。登录后第一件事：右上角头像 → 个人资料 → 修改密码（向导里设的只是初始密码）。
登录后进「管理」菜单，把这几项基础数据填上，资产台账才有骨架：
- 厂商管理：录入联想、戴尔等供应商，后续设备型号要引用它
- 资产分类：建"笔记本""显示器""软件"等分类
- 状态标签：配置"可用/在库/维修中/报废"等状态
- 位置：办公室、机房等物理位置
上线之后的三层验证，确认"真的部署成功了"
光能打开登录页不算完，按下面三层走一遍冒烟测试，才算真正交付：
第一层：页面功能冒烟
- 新建一个分类 → 新建一个厂商 → 新建一条资产（不填序列号也能建，但建议填）
- 给资产打二维码标签（列表页的二维码图标），确认图片能正常生成
- 记一条维护记录，确认日期、费用字段能保存
第二层：数据与日志验证
# 应用日志无异常堆栈 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两个容器均为 Upcurl 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考