发表更新网络16 分钟读完 (大约2420个字)0次访问

群晖 DSM7 使用 Docker Compose 部署 NetBox 教程

群晖 DSM7 使用 Docker Compose 部署 NetBox 教程

适用场景：在群晖 DSM7 上通过 Docker Compose 部署 NetBox，参考本次 10.139.27.3 群晖 SSH 操作记录整理。
目标访问地址示例：http://10.139.27.3:9999
本文已对原 SSH 记录中的密码、SECRET_KEY、数据库密码、Redis 密码、API Token 等敏感信息做脱敏处理。

0. 本次成功部署的关键信息

项目 本次记录
群晖地址 10.139.27.3
SSH 用户 bg4vrg
部署目录 /volume3/dockerconf/netbox
NetBox Web 外部端口 9999
容器内部端口 8080
访问地址 http://10.139.27.3:9999
NetBox 镜像 docker.io/netboxcommunity/netbox:v4.6-5.0.1
PostgreSQL 镜像 docker.io/postgres:18-alpine
Redis/Cache 镜像 docker.io/valkey/valkey:9.0-alpine
管理员用户名 suyu
管理员密码 不写入文档，建议用 changepassword 重置

说明：原 SSH 日志里出现过明文密码和各种密钥。搭建教程里不要长期保存这些内容，生产环境也建议重新生成并妥善保存。

1. 准备工作

1.1 群晖套件

确认群晖已经安装并启用：

1
2
Container Manager / Docker
SSH 服务

DSM 里开启 SSH：

1
控制面板 -> 终端机和 SNMP -> 启用 SSH 功能

1.2 SSH 登录群晖

从电脑使用 MobaXterm / Windows Terminal / Xshell 登录：

1
ssh [email protected]

切换 root：

1
sudo -i

2. 创建部署目录

本次成功部署目录是：

1
/volume3/dockerconf/netbox

创建目录：

1
2
mkdir -p /volume3/dockerconf/netbox
cd /volume3/dockerconf/netbox

注意：不要放在 /root 或非共享卷路径里。群晖升级或重启时，非共享目录里的数据存在不可控风险。

3. 获取 netbox-docker 项目文件

方案 A：群晖有 git

如果群晖已经有 git：

1
2
cd /volume3/dockerconf/netbox
git clone -b release https://github.com/netbox-community/netbox-docker.git .

这里最后的 . 表示直接把项目文件放到当前目录，也就是：

1
/volume3/dockerconf/netbox

这样后面直接在这个目录执行：

1
docker compose ...

方案 B：群晖没有 git

本次记录里曾出现过：

1
-ash: git: command not found

如果你的群晖也没有 git，可以在电脑上下载 netbox-docker 的 release 分支 ZIP，然后上传到：

1
/volume3/dockerconf/netbox

解压后确保目录里能看到这些文件：

1
ls -lah /volume3/dockerconf/netbox

正常应看到类似：

1
2
3
4
5
6
docker-compose.yml
docker-compose.override.yml.example
configuration/
env/
Dockerfile
README.md

如果解压后变成：

1
/volume3/dockerconf/netbox/netbox-docker/docker-compose.yml

可以进入子目录执行，也可以把里面内容移动到 /volume3/dockerconf/netbox 根目录。为了后续命令统一，推荐最终结构是：

1
2
3
/volume3/dockerconf/netbox/docker-compose.yml
/volume3/dockerconf/netbox/configuration/
/volume3/dockerconf/netbox/env/

4. 创建 docker-compose.override.yml

这是最关键的一步。不要手工在 vim 里一点点改，容易把 YAML 缩进弄坏。建议直接用 cat > 文件 <<'EOF' 的方式一次性写入。

进入目录：

1
cd /volume3/dockerconf/netbox

写入 override 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
cat > docker-compose.override.yml <<'EOF'
services:
  netbox:
    ports:
      - "9999:8080"
    healthcheck:
      start_period: 300s
    environment:
      SKIP_SUPERUSER: "false"
      SUPERUSER_NAME: "suyu"
      SUPERUSER_EMAIL: "[email protected]"
      SUPERUSER_PASSWORD: "请改成你自己的强密码"
EOF

4.1 这段 YAML 的含义

1
2
services:
  netbox:

表示只覆盖 netbox 这个服务。

1
2
ports:
  - "9999:8080"

表示群晖 9999 端口映射到容器里的 8080。所以浏览器访问：

1
http://10.139.27.3:9999
1
2
healthcheck:
  start_period: 300s

表示启动后给 NetBox 300 秒初始化时间。首次启动时数据库迁移较慢，默认时间可能不够。

1
2
3
4
5
environment:
  SKIP_SUPERUSER: "false"
  SUPERUSER_NAME: "suyu"
  SUPERUSER_EMAIL: "[email protected]"
  SUPERUSER_PASSWORD: "请改成你自己的强密码"

表示首次启动时尝试创建超级管理员。

注意：如果数据库已经存在，SUPERUSER_PASSWORD 不一定会修改已有用户密码。忘记密码时，优先用 changepassword，不要靠反复改 YAML。

5. 检查 YAML 是否正确

执行：

1
2
cd /volume3/dockerconf/netbox
docker compose config

如果没有报错，说明 YAML 基本没问题。

之前踩过的典型错误有：

错误 1：ports 写成一行

错误写法：

1
2
services:
  netbox:    ports:- "9999:8080"

正确写法：

1
2
3
4
services:
  netbox:
    ports:
      - "9999:8080"

错误 2：environment 放到根层级

错误写法：

1
2
3
4
5
6
7
services:
  netbox:
    ports:
      - "9999:8080"

environment:
  SUPERUSER_NAME: "suyu"

会报类似：

1
Additional property environment is not allowed

正确写法：

1
2
3
4
services:
  netbox:
    environment:
      SUPERUSER_NAME: "suyu"

错误 3：中文引号或隐藏字符

不要用：

1
SUPERUSER_PASSWORD: “password”

要用英文半角引号：

1
SUPERUSER_PASSWORD: "password"

6. 修复群晖 ACL / 权限问题

本次部署时，NetBox 容器曾经因为读不到配置目录而报错：

1
PermissionError: [Errno 13] Permission denied: '/etc/netbox/config/'

建议启动前直接修复权限：

1
2
3
4
5
6
7
cd /volume3/dockerconf/netbox

chmod 755 /volume3/dockerconf
chmod 755 /volume3/dockerconf/netbox

find configuration -type d -exec chmod 755 {} \;
find configuration -type f -exec chmod 644 {} \;

检查：

1
2
ls -ld configuration
ls -l configuration

正常应类似：

1
2
3
4
5
drwxr-xr-x  configuration
-rw-r--r--  configuration.py
-rw-r--r--  extra.py
-rw-r--r--  logging.py
-rw-r--r--  plugins.py

7. 拉取镜像并启动

拉取镜像：

1
2
cd /volume3/dockerconf/netbox
docker compose pull

启动：

1
docker compose up -d

首次启动需要等待数据库初始化和迁移，可能需要几分钟。

查看状态：

1
docker compose ps

查看日志：

1
docker compose logs -f netbox

如果看到大量：

1
Applying xxx. OK

说明数据库迁移正在进行，不要急着重启。

8. 判断是否启动成功

执行：

1
docker compose ps

理想状态：

1
2
3
4
5
netbox-postgres-1       running
netbox-redis-1          running
netbox-redis-cache-1    running
netbox-netbox-1         healthy
netbox-netbox-worker-1  running

本次记录里最终出现过：

1
2
Container netbox-netbox-1         Healthy
Container netbox-netbox-worker-1  Started

这就是成功标志。

浏览器访问：

1
http://10.139.27.3:9999

9. 创建或重置管理员账号

9.1 首次创建管理员

如果环境变量没有自动创建用户，执行：

1
2
cd /volume3/dockerconf/netbox
docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

按提示输入用户名、邮箱、密码。

建议用户名：

1
suyu

9.2 忘记密码时重置

如果已经有 suyu 用户，但忘记密码：

1
2
cd /volume3/dockerconf/netbox
docker compose exec netbox /opt/netbox/netbox/manage.py changepassword suyu

如果不确定有哪些用户：

1
docker compose exec netbox /opt/netbox/netbox/manage.py shell -c "from django.contrib.auth import get_user_model; U=get_user_model(); print(list(U.objects.values_list('username','is_superuser','is_active')))"

10. 常用运维命令

查看容器状态

1
2
cd /volume3/dockerconf/netbox
docker compose ps

查看 NetBox 日志

1
docker compose logs --tail=200 netbox

实时跟踪：

1
docker compose logs -f netbox

重启 NetBox Web

1
docker compose restart netbox

重启全部服务

1
docker compose restart

停止服务

1
docker compose stop

启动服务

1
docker compose up -d

11. 备份与恢复

11.1 备份数据库

创建备份目录：

1
mkdir -p /volume3/dockerconf/netbox/backup

导出 PostgreSQL：

1
2
cd /volume3/dockerconf/netbox
docker compose exec -T postgres pg_dump -U netbox netbox > /volume3/dockerconf/netbox/backup/netbox_$(date +%F).sql

11.2 备份配置文件

1
2
cd /volume3/dockerconf
tar czf /volume3/dockerconf/netbox/backup/netbox_config_$(date +%F).tar.gz netbox/docker-compose.yml netbox/docker-compose.override.yml netbox/configuration netbox/env

11.3 千万不要随便执行

不要执行：

1
docker compose down -v

-v 会删除 volume，可能导致 PostgreSQL 数据库、媒体文件等被删除。

如果只是停止容器，用：

1
docker compose down

或者：

1
docker compose stop

12. 后续升级建议

升级前先备份：

1
2
3
4
cd /volume3/dockerconf/netbox
mkdir -p backup
docker compose exec -T postgres pg_dump -U netbox netbox > backup/netbox_before_upgrade_$(date +%F).sql
tar czf backup/netbox_files_before_upgrade_$(date +%F).tar.gz docker-compose.yml docker-compose.override.yml configuration env

再拉取新镜像：

1
2
docker compose pull
docker compose up -d

观察日志：

1
docker compose logs -f netbox

等 netbox-netbox-1 变成 healthy 再访问页面。

13. 本次踩坑复盘

13.1 目录写错

曾经尝试：

1
cd /dockerconf/netbox

但实际目录是：

1
cd /volume3/dockerconf/netbox

13.2 群晖没有 nano

日志里出现过：

1
-ash: nano: command not found

所以建议使用：

1
2
3
cat > docker-compose.override.yml <<'EOF'
...
EOF

这样比 vim 手改更稳。

13.3 YAML 缩进错误

错误写法：

1
2
services:
  netbox:    ports:- "9999:8080"

正确写法：

1
2
3
4
services:
  netbox:
    ports:
      - "9999:8080"

13.4 environment 层级错误

错误写法会导致：

1
Additional property environment is not allowed

environment 必须放在：

1
2
3
services:
  netbox:
    environment:

下面。

13.5 群晖 ACL 权限导致容器读不到配置

错误：

1
PermissionError: [Errno 13] Permission denied: '/etc/netbox/config/'

解决：

1
2
3
4
5
cd /volume3/dockerconf/netbox
chmod 755 /volume3/dockerconf
chmod 755 /volume3/dockerconf/netbox
find configuration -type d -exec chmod 755 {} \;
find configuration -type f -exec chmod 644 {} \;

13.6 首次启动时间不够

首次数据库迁移比较慢，如果 healthcheck 太早判定失败，会出现 unhealthy。建议：

1
2
healthcheck:
  start_period: 300s

14. 最终推荐 docker-compose.override.yml

下面是推荐保留版，敏感信息请自行替换：

1
2
3
4
5
6
7
8
9
10
11
services:
  netbox:
    ports:
      - "9999:8080"
    healthcheck:
      start_period: 300s
    environment:
      SKIP_SUPERUSER: "false"
      SUPERUSER_NAME: "suyu"
      SUPERUSER_EMAIL: "[email protected]"
      SUPERUSER_PASSWORD: "请改成你自己的强密码"

15. 部署完成后的 NetBox 资产导入注意事项

你后续资产导入已经约定：

1
2
3
4
5
CSV 必须 UTF-8 with BOM
Region 表示宿豫区下的乡镇街道
Site 表示独立物理地点
Location 表示站点内部楼层/房间/弱电间/户籍窗口/电梯厅
Rack 表示具体机柜或弱电箱

推荐资产基础数据导入顺序：

1
2
3
4
5
6
7
8
9
10
11
12
1. Region / 地区
2. Site Group / 站点组
3. Site / 站点
4. Location / 位置
5. Rack / 机柜
6. Device Role / 设备角色
7. Manufacturer / 厂商
8. Device Type / 设备型号
9. Device / 设备上架
10. Interface / 接口
11. IP / Prefix / VLAN
12. Cable / Circuit / Power

16. 一句话版流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
ssh [email protected]
sudo -i
mkdir -p /volume3/dockerconf/netbox
cd /volume3/dockerconf/netbox
# 准备 netbox-docker 项目文件
cat > docker-compose.override.yml <<'EOF'
services:
  netbox:
    ports:
      - "9999:8080"
    healthcheck:
      start_period: 300s
    environment:
      SKIP_SUPERUSER: "false"
      SUPERUSER_NAME: "suyu"
      SUPERUSER_EMAIL: "[email protected]"
      SUPERUSER_PASSWORD: "请改成你自己的强密码"
EOF
chmod 755 /volume3/dockerconf /volume3/dockerconf/netbox
find configuration -type d -exec chmod 755 {} \;
find configuration -type f -exec chmod 644 {} \;
docker compose config
docker compose pull
docker compose up -d
docker compose logs -f netbox

访问：

1
http://10.139.27.3:9999

群晖 DSM7 使用 Docker Compose 部署 NetBox 教程

https://bg4vrg.com/post/20260630205930.html

作者

fei

发布于

2026-06-30

更新于

2026-06-30

许可协议

#

喜欢这篇文章？打赏一下作者吧

评论

最新文章

分类

广告

×