先把话放前面WandBWeights Biases这款实验追踪工具SaaS 版用着确实顺手但一旦涉及内网隔离、客户数据不出域、或者团队规模大到按席位计费肉疼的时候本地部署就成了绕不开的选项。我前后折腾了两周多从 Docker 启动到 License 授权踩过的坑比想象中多得多。这篇就把完整流程拆开讲清楚从镜像选择、数据持久化讲到 License 的申请与更新末尾附上我实测遇见的报错和对应解法给正要动手的团队一个能直接照做的参考。WandB 本地部署这件事官方文档只告诉你“跑一个容器就行”但真正操作时会发现卡住你的往往不是容器本身而是 Docker Desktop 的虚拟化检测、镜像版本选择、端口规划、License 的生效时机这些文档里一笔带过的细节。下面按我的实操顺序来。1. 先聊清楚什么情况下必须自己部署 WandB1.1 SaaS 版真香但有几个硬伤WandB 的云端服务体验确实好注册就能用实验仪表盘、超参对比、模型版本管理都做得几乎是零门槛。但有几个场景会逼着你换本地版数据合规实验数据、模型权重、训练日志不允许上传到第三方服务器。很多金融、医疗、政企项目在需求阶段就写明了“数据不出内网”这时候 SaaS 版直接出局。网络环境训练机在隔离区只有内网 IP出网要过审批甚至完全没有外网。你总不能让每台训练机都去云端登录吧。长期成本按团队席位买 SaaS 版人一多账单涨得飞快而本地版是一次性基础设施投入。说白了本地部署不是因为它比 SaaS 功能强而是因为它在“数据主权”和“网络边界”这两件事上不可替代。1.2 本地版能覆盖哪些核心能力部署完本地版之后SaaS 版常用的功能基本都有实验跟踪loss/accuracy 曲线、超参表、系统资源监控项目看板多实验对比、筛选排序报告与分享生成 Markdown 形式的实验报告团队内网访问模型注册与版本管理配合模型产物存储能追溯每次实验的权重和指标需要注意本地版默认使用 SQLite 存储元数据文件存储走本地磁盘。这意味着它不擅长支撑“几百人同时高频写入”的规模但一个几十人的算法团队日常使用完全没问题。1.3 部署前的资源评估我建议的起步配置资源最低要求推荐配置CPU2 核4 核及以上内存4 GB8 GB磁盘20 GB100 GB独立分区操作系统Linux/Windows/macOSLinux 服务器优先磁盘一定要留足因为每个实验的日志、系统指标、模型输出都会往/vol下面写。我见过最夸张的一次一个团队跑了三个月存储涨了 60 多 GB里面全是checkpoint和中间产物。2. Docker 启动前的硬准备虚拟化、镜像、端口一个都不能少2.1 Docker Desktop 启动失败的“元凶”是虚拟化很多人在 Windows 上装完 Docker Desktop点启动直接弹红字Docker Desktop failed to start because virtualisation support wasnt detected这个报错九十年代就存在了但至今还是高频问题。本质是 Docker Desktop 在 Windows 上依赖 Hyper-V 或 WSL2 后端而后端又依赖 CPU 虚拟化指令集Intel VT-x 或 AMD SVM。排查链条很固定打开任务管理器 → 性能 → CPU看“虚拟化”这一项是否显示“已启用”如果显示“已禁用”重启进 BIOS/UEFI找到 Intel Virtualization Technology 或 AMD SVM Mode设为 Enabled如果已经是 Enabled检查 Windows 功能里“虚拟机平台”和“适用于 Linux 的 Windows 子系统”是否勾选没勾选就勾上重启还要确认 Hyper-V 没被完全关闭可以在管理员 PowerShell 里执行bcdedit /set hypervisorlaunchtype auto然后重启电脑。有朋友问是不是必须换 Linux 才能跑不是。Windows 加 WSL2 跑 WandB 本地版我验证过没问题但生产环境我强烈建议直接放 Linux 服务器上省掉一层虚拟化开销后面排查问题也少一个变量。2.2 镜像版本锁定不要裸奔在 latest 上WandB 官方镜像名是wandb/localDocker Hub 上可以直接拉。很多教程让你直接docker pull wandb/local:latest这是典型的坑原因有两点大版本升级可能带来 SQLite schema 迁移旧数据没备份就拉新镜像重启容器能起但网页端可能报错latest每次拉取结果都不一样你无法保证开发环境和线上环境镜像一致我建议的做法docker pull wandb/local:latest docker inspect wandb/local:latest --format {{.Id}}拉完记录下镜像 ID然后在 compose 文件里固定到具体版本 tag后续验证没问题再统一升级。没有特定 tag 时至少用镜像 ID 做唯一性确认。2.3 端口规划与数据目录提前定死WandB 容器默认监听8080端口映射到宿主机也是8080。如果宿主机上已经有别的服务占了 8080容器能起来但访问不了。排查占用ss -ltnp | grep 8080Windows 下则是netstat -ano | findstr 8080有占用就把宿主机端口换掉例如ports: - 9090:8080这样内网访问地址就变成http://你的服务器IP:9090。数据目录是容器里的/vol里面放 SQLite 数据库文件和文件存储。这个路径必须在启动前规划好因为所有实验数据都在这下面。我的建议是挂载到宿主机一个大分区上比如/var/lib/wandb不要挂在根分区否则磁盘满了连系统都跟着遭殃。3. Docker Compose 落地细节从一次性容器到可维护服务3.1 compose 文件逐字段拆解官方文档给的是裸docker run适合快速验证但生产环境我建议直接用 Docker Compose。最小可用配置长这样services: wandb: image: wandb/local:你的版本tag container_name: wandb-local restart: always ports: - 8080:8080 environment: - LICENSE你的license_key volumes: - /var/lib/wandb:/vol几个字段为什么要这么写restart: always服务器重启后容器自动拉起不用手动干预这是服务化部署的基本要求LICENSE环境变量License 不是启动后在网页里填的而是通过环境变量注入这一点后面专门讲/var/lib/wandb:/vol挂载容器可以随时删掉重建但数据必须留在宿主机上启动方式docker compose up -d启动后看日志docker logs -f wandb-local看到类似服务已启动的日志后浏览器访问http://localhost:8080首次打开会引导创建管理员账号。3.2 数据持久化与备份做一次就够我曾经手滑删掉过容器幸好当时挂载了数据卷重来一个容器数据全回来了。要是没挂载整个实验库会直接消失。备份操作记住三步docker stop wandb-local tar czf wandb-backup-$(date %F).tar.gz /var/lib/wandb docker start wandb-local备份前先停容器是为了避免 SQLite 在写过程中被拷贝导致文件不一致。如果你不想停服也可以用sqlite3的在线备份命令但对大多数团队凌晨停机备份就够了。恢复就更简单把备份解压回/var/lib/wandb然后启动容器。3.3 升级的正确姿势先备份再换 tag升级 WandB 本地版千万不要在网页上看到提示就点刷新。正确流程备份/var/lib/wandb上面那个 tar 命令修改 compose 文件里的镜像 tag执行docker compose pull执行docker compose up -d这个过程中要注意如果新版本有数据库迁移逻辑首次启动会跑一会儿 migration日志里能看到相关输出别急着判断“卡住了”。我在一次升级后等了将近十分钟以为出了问题实际上是在迁移历史实验数据。4. License 的全生命周期申请、下发、更新、报错处理4.1 免费 License 怎么申请WandB 本地版支持免费 License面向个人和学术用途。申请的入口通常有两个第一次访问本地版网页端时登录页会引导你申请从官方网站的本地部署页面进入申请通道申请提交后License key 会发到邮箱是一串形如xxxx-xxxx-xxxx-xxxx的字符串。免费版和企业版的差异主要在功能限制和支撑级别上具体以官方当时的策略为准。你要是给公司搭先确认清楚要免费版还是企业版避免后面授权不足再返工。4.2 License 正确下发方式环境变量优先我见过很多人拿到 key 后先进网页端找“输入 License”的地方。可以明确说不要这么做。网页端即使能填也容易遇到权限不足或被覆盖的情况。正确的做法是把 License 写进 docker-compose.ymlenvironment: - LICENSE你的license_key然后重新创建容器docker compose up -d --force-recreate wandb为什么必须--force-recreate因为环境变量是容器创建时注入的普通docker restart不会重新读取环境变量。很多人改了 compose 文件后只 restart发现 License 没生效就是这个原因。4.3 更新 License 的完整流程License 有有效期的话过期前更新流程和首次配置一致拿到新 key备份数据图个心安虽然改 License 不碰数据但顺手做个备份没坏处修改 compose 文件中的LICENSE环境变量docker compose up -d --force-recreate wandb查看日志确认 License 校验通过注意更新前最好把旧容器先docker compose down再up -d避免端口和旧容器冲突。4.4 常见 License 报错怎么处理很多人会遇到类似“you do not have permission to enter a license key”的提示这通常分两种场景在网页端用非管理员账号尝试更新 License权限不够服务器限制了 License 写入路径比如文件系统只读解决思路全部回到部署层操作。用管理员账号登录服务器修改 compose 环境变量重新创建容器然后刷新网页端看状态。绕开网页端的权限体系是最稳定的路径。还有一种情形是 License 环境变量写在容器里但镜像版本升级后校验逻辑变了报出“invalid license”或“license check failed”。这种先确认一下你拉取的镜像版本和 License 类型是否匹配比如免费版 key 用在企业版镜像上就可能校验失败。5. 高频报错排查手记从现象到根因下面这些是我实测遇到过或者帮同事排查过的问题按频率排序。5.1 容器启动后立刻退出或反复重启现象docker ps看到容器状态一直Restarting日志刷报错。常见原因和对应解法现象根因解法日志提示权限不足挂载目录/var/lib/wandb属主不对chmod -R 777 /var/lib/wandb或调整属主日志提示端口占用宿主机的 8080 被占换映射端口或者停掉占用进程日志提示数据库文件损坏之前没有挂载数据卷容器反复重建导致恢复备份重建挂载日志提示 OOM内存不够容器被杀给 Docker 分配更大内存或减小系统其他负载挂载目录权限问题特别容易出现在 Linux 上。容器内部进程以非 root 用户运行写到宿主机的挂载目录时如果目录属主是 root权限不够就会启动失败。稳妥做法是sudo mkdir -p /var/lib/wandb sudo chown -R 1000:1000 /var/lib/wandb5.2 网页能开但训练脚本连不上这个是本地部署里最多人踩的坑。现象是浏览器能打开http://localhost:8080但训练脚本一跑就报 connection 超时或无法解析地址。根因往往是你的训练代码还在用 SaaS 版的默认地址或者没有走本地服务。解决办法在训练脚本里显式指定本地地址import wandb wandb.login(hosthttp://192.168.1.100:8080) wandb.init(projectmy-project)或者不写代码在环境变量层面统一配置export WANDB_BASE_URLhttp://192.168.1.100:8080 export WANDB_API_KEY你的api_key python train.py推荐第二种方式因为不用改代码所有训练脚本统一生效。前提是你得先在本地版网页端创建账号然后在个人设置里生成一个 API key填到环境变量里。训练机和 WandB 服务不在同一台机器的话还要检查防火墙和安全组策略。内网服务器之间 8080 端口可能默认不通手动放行一下。5.3 登录页刷不出来一直转圈这种问题常见于改过 DNS 或代理的环境。WandB 容器启动时某些版本会做外网校验如果你在内网隔离环境外网访问超时会拖慢页面加载。解决思路看容器日志确认卡在哪一步如果确实在尝试外网校验考虑在镜像文档里找对应的环境变量关闭外网连接检测对于完全离线的内网机把容器镜像在有网的机器上docker save/load迁移过去同时准备好离线部署需要的所有配置5.4 磁盘写满导致容器进入只读状态数据量大以后挂载分区满了容器日志开始出现 file write 相关错误甚至直接挂掉。处理方法df -h看磁盘占用清理/vol下不需要的 run 目录或旧备份如果经常写满把挂载目录迁移到大容量磁盘上这里提醒一句清理/vol里的实验数据之前确认没有需要保留的模型产物和报告。最好先备份再清理磁盘便宜数据丢了真找不回来。6. 给后来者的小建议如果让我重新来一遍我会把下面这几件事放到最前面做第一先确认虚拟化已开启、端口没有被占、挂载目录所在磁盘足够大。这三个前置条件花十分钟检查完后面能少踩一半的坑。第二License 不要留到容器启动之后再去网页端操作直接写进 compose 文件的环境变量里改起来也方便。记住改了环境变量一定要--force-recreate而不是restart。第三升级镜像前无论多自信一定备份/var/lib/wandb。我吃过一次亏之后定了规矩没有备份不升级。这个习惯救过我第二次。还有一点不要用latest做生产部署。固定版本 tag升级时走“备份、拉新镜像、重建容器、看日志”这条链路稳定压倒一切。等到你发现网页端能正常访问、训练脚本能顺利上传指标、License 状态显示正常这套 WandB 本地部署才算真正落地。到时候再回头看Docker 和 License 这些坑其实都是流程问题流程顺了一切也就顺了。