W&B NAS私有化安装教程：新手入门与性能优化参数

为什么把 Weights & Biases 部署到 NAS

Weights & Biases 常用于记录机器学习实验、训练指标、模型版本、数据集变更和团队协作信息。对于个人开发者，使用云端服务通常最省事；但在企业实验室、学校课题组或本地算力集群中，训练日志、模型文件、样本说明可能不适合直接上传到外部平台，这时把服务私有化部署在 NAS 上，是一种兼顾易用性和数据可控性的方案。

NAS 的优势在于长期在线、存储容量大、管理界面友好，适合承载实验元数据、模型产物和可视化看板。需要注意的是，NAS 并不等同于高性能服务器。如果团队同时有大量训练任务写入日志，或者需要保存较多大文件，必须提前规划磁盘、内存、网络和备份策略，避免后期出现响应慢、页面加载失败或存储空间被快速占满的问题。

适用场景与部署前提

这种安装方式适合三类用户：第一，已有群晖、威联通或自建 Linux NAS，希望在内网统一管理训练结果；第二，团队不想让实验数据离开本地环境；第三，需要给多名成员提供统一账号、项目空间和可追溯记录。若只是单人临时测试，也可以先在普通工作站上用 Docker 试跑，确认流程后再迁移到 NAS。

部署前建议准备以下条件：NAS 至少 4 核 CPU、8GB 内存，推荐 16GB 以上；系统盘和数据盘分开更稳妥；Docker 或 Container Manager 已可用；内网 DNS 或固定 IP 已配置；准备一个独立目录用于持久化数据，例如 /volume1/docker/wandb；如果后续要通过域名访问，建议提前准备反向袋里和证书。训练机器需要能访问 NAS 的服务端口，且时间同步正常，否则实验记录可能出现时间线混乱。

安装思路：先跑通，再加固，再优化

新手最容易犯的错误，是一开始就同时配置外部对象存储、反向袋里、邮件服务和复杂权限，结果问题难以定位。更稳妥的流程是分三步：先用官方容器在 NAS 上跑通服务；确认浏览器能登录、训练脚本能写入日志；最后再配置持久化、访问入口、备份和性能参数。

在 NAS 管理界面中创建容器时，镜像可选择 W&B 官方本地服务镜像，常见名称为 wandb/local 或官方当前推荐的 server 镜像，实际以官方文档为准。端口通常映射到 Web 服务端口，例如宿主机 8080 对应容器服务端口。数据目录必须做持久化映射，否则容器重建后项目和实验记录可能丢失。环境变量中可设置服务访问地址，例如 HOST=http://nas-ip:8080，便于客户端正确回传链接。

NAS 图形界面部署步骤

第一步，在 NAS 上打开容器管理工具，搜索并下载 W&B 本地服务镜像。若 NAS 无法直接拉取镜像，可在一台能正常访问镜像源的电脑上拉取后导出，再导入到 NAS。导入镜像时要核对版本号，不建议长期使用来源不明的镜像。

第二步，创建持久化目录。建议至少建立 data、logs、backups 三个子目录。容器内数据目录映射到 NAS 的 data，日志映射到 logs，备份文件放入 backups。目录权限要允许容器进程读写，但不建议直接给所有用户完全控制权限。

第三步，配置端口和环境变量。端口可用 8080:8080，如果 NAS 已有服务占用该端口，可改成 18080:8080。环境变量中填写外部访问地址、管理员邮箱、数据目录等参数。首次启动后，查看容器日志，重点确认数据库初始化、服务监听端口、存储目录权限是否正常。

第四步，浏览器访问 http://NAS地址:端口，完成初始化账号。创建首个管理员后，建议立刻进入系统设置，关闭不需要的公开注册，改为邀请制或管理员创建账号。团队项目命名要提前约定，例如按课题、模型线或业务线划分，避免后期项目列表混乱。

命令行部署参考

如果 NAS 支持 SSH，也可以使用命令行部署，便于复制和排查。基本思路是先创建目录，再启动容器。例如创建 /volume1/docker/wandb 作为根目录，将容器数据挂载进去，同时设置重启策略为 unless-stopped，确保 NAS 重启后服务自动恢复。

命令行方式的优点是参数清晰、便于版本管理；缺点是对新手不如图形界面直观。无论采用哪种方式，关键点都相同：镜像来源可信、数据目录持久化、端口不冲突、访问地址填写正确、日志可查看。不要把核心数据只放在容器内部，也不要在没有备份的情况下随意删除旧容器卷。

客户端连接与基础验证

服务端启动后，在训练机器上安装 Python 客户端：pip install wandb。然后设置服务地址，例如通过环境变量指定 WANDB_BASE_URL=http://NAS地址:端口。首次登录可使用页面生成的 API Key，执行 wandb login 后粘贴密钥。为了避免不同环境互相干扰，建议在每台训练机上单独确认当前 base url。

验证时不要直接运行大型训练任务。可以先写一个最小脚本，记录 loss、accuracy 和少量配置参数，确认页面能看到 run、曲线能刷新、文件能上传。再测试断点恢复、多人登录、项目权限和模型文件上传。若使用 PyTorch Lightning、Transformers Trainer 或其他训练框架，也要确认其集成参数指向本地服务。

性能优化参数与容量规划

NAS 部署最常见瓶颈是磁盘 I/O、内存和小文件数量。建议优先使用 SSD 缓存或 SSD 存储卷承载元数据目录，把大文件产物放到容量盘或兼容对象存储的后端。若团队会频繁上传模型权重，应限制单次上传体积，或制定只上传关键 checkpoint 的规则，避免每个 epoch 都保存完整文件。

容器资源方面，建议给服务预留 2 到 4 核 CPU、4GB 到 8GB 内存起步。并发较高时，可提高到 8 核、16GB 内存。若容器管理器支持资源限制，可设置内存上限和日志轮转，防止服务异常时拖慢 NAS 其他应用。常用优化方向包括：增大后端数据库连接上限、启用对象存储后端、提高文件句柄数量、限制单项目保留周期、定期清理废弃 run 和未使用 artifacts。

在反向袋里层面，可适当提高请求体大小限制和超时时间，否则上传较大模型文件时可能中断。袋里超时可从 60 秒提高到 300 秒，上传体积限制按团队实际需要设置。若只是记录训练指标，不建议放开过大的上传限制；若需要保存模型产物，应配合项目规范和清理策略。

安全边界与权限建议

私有化安装不代表天然安全。首先，不建议把服务直接暴露到公网；如确有远程访问需求，应通过受控入口、强口令、证书和访问白名单实现。其次，管理员账号要开启强密码策略，离职或不再参与项目的成员应及时停用账号。API Key 等同于写入凭据，不应写进公开仓库、截图或共享文档。

训练日志中可能包含数据路径、样本标签、超参数、备注说明等信息，团队应约定哪些内容可以记录，哪些内容需要脱敏。对于包含敏感样本的项目，建议只记录统计指标和必要配置，不上传原始样本。备份文件同样需要妥善保存，因为备份中往往包含完整项目历史和用户信息。

常见问题排查

页面打不开，先检查容器是否运行、端口映射是否正确、NAS 防护规则是否允许内网访问。若容器不断重启，查看日志中是否有目录权限不足、数据库初始化失败或端口占用提示。若浏览器能打开但客户端登录失败，重点检查 WANDB_BASE_URL 是否和页面地址一致，API Key 是否来自同一个服务实例。

上传文件失败，常见原因是反向袋里限制、磁盘空间不足、容器数据目录无写入权限或请求超时。曲线刷新慢，多半与 NAS 性能、项目 run 数量过多或浏览器一次加载数据太大有关，可按项目归档旧实验，减少单个项目中的历史记录。若时间显示异常，检查 NAS 和训练机器的时间同步设置。

升级失败或升级后异常时，不要直接覆盖旧数据。正确做法是先停止容器，完整备份数据目录和配置，再拉取新版本镜像测试。升级后若出现不可兼容问题，可用旧镜像和旧数据恢复。生产环境建议固定镜像版本，不要使用会自动变化的标签，以免在重启时意外升级。

备份、升级与日常维护

建议设置每日至少一次配置和数据备份，重要项目在训练高峰期可增加备份频率。备份不仅要存在 NAS 本机，也应定期复制到另一台存储设备，防止单点故障。备份完成后要做恢复演练，确认不是只有文件、没有可用恢复流程。

日常维护重点包括：监控磁盘占用、清理无用 artifacts、检查容器日志大小、审计账号列表、记录版本变更。对于多人团队，可指定一名维护负责人，统一处理升级、账号、项目归档和容量扩容。只要前期把持久化、权限、备份和性能参数规划好，NAS 上的 W&B 可以成为稳定的本地实验管理平台，让训练过程更透明、结果更容易复现。