Visdom 安装与部署实战指南：pip 安装、源码构建、服务器启动与问题排查

Visdom 是面向 AI/ML 实验的实时可视化工具，Python 客户端与 Web 前端随 Python 服务端一并分发，安装后即可在同一端口下完成"服务端启动 + 浏览器访问 + Python 绘图"的完整闭环。本文以官方安装文档为主线，结合本仓库的源码实现，系统讲解从 pip/源码安装、虚拟环境隔离、可选依赖，到服务器启动、命令行配置、HTTPS 与登录认证，再到常见安装问题的完整排查路径，帮助你在一台新机器上从零跑起 Visdom 并定位绝大多数安装类故障。

安装前置条件

官方文档给出的最低要求如下：

• Python 3.6 或更高版本
• pip（随 Python 一并安装）
• 现代 Web 浏览器（Chrome、Firefox、Safari、Edge）

需要特别说明的是，当前仓库的实际要求比文档更严格：setup.py 中声明了 python_requires=">=3.12"（见 setup.py），同时 py/visdom/init.py 与 py/visdom/server/main.py 在导入时都会直接抛出 RuntimeError("Visdom requires Python 3.12 or newer.")。因此在实际环境中，请优先使用 Python 3.12 及以上版本，否则即便安装成功，导入或启动时也会被显式拒绝。

方式一：通过 pip 安装（推荐）

最简单的安装方式，直接使用 pip 安装 PyPI 上发布的 visdom 包：

pip install visdom

从 setup.py 的 install_requires 可以看到，安装时会自动带上以下核心运行时依赖：numpy、scipy、requests、tornado、jsonpatch、websocket-client、networkx、openTSNE 以及 pillow。其中 tornado 承担 HTTP 与 WebSocket 服务，openTSNE 为 embeddings 可视化提供 t-SNE 降维能力。

方式二：从源码安装

需要安装仓库最新开发版本时，可以直接从 git 仓库安装：

pip install git+https://github.com/fossasia/visdom

对于参与开发的场景，建议克隆仓库并以**可编辑模式（editable mode）**安装，这样代码改动即时生效，无需重复安装：

git clone https://github.com/fossasia/visdom.git
cd visdom
pip install -e .

仓库的打包配置在 setup.py 中：包体从 py 目录下收集（package_dir={"": "py"}），并将 visdom/static 下的静态资源与 py.typed、*.pyi 一并打包，同时注册了控制台入口 visdom=visdom.server.run_server:download_scripts_and_run——这正是后文 visdom 命令的来源。

使用虚拟环境隔离依赖

为避免与其他项目产生依赖冲突，官方文档推荐在虚拟环境中安装 Visdom：

python -m venv visdom-env
source visdom-env/bin/activate   # Linux/macOS
# visdom-env\Scripts\activate    # Windows

pip install visdom

虚拟环境创建了与系统 Python 隔离的独立依赖树，尤其适合在同一台机器上同时维护多个深度学习实验环境，避免 numpy、pillow 等依赖版本互相污染。

可选依赖：plotly 与 kaleido

如果希望在代码中直接将 Plotly 图形保存为图片文件（PNG/SVG 等），而不用在浏览器里手动点击下载按钮，需要额外安装两个包：

pip install plotly kaleido

两者的分工在源码中非常清晰：

• plotly：提供 plotly.graph_objects 等绘图对象，以及 plotly.utils.PlotlyJSONEncoder 序列化能力（见 py/visdom/init.py 中 plotlyplot 的实现：先对 figure 做 JSON 往返编码以处理 numpy 数组等边界情况，再转发给前端渲染）；
• kaleido：承担离屏渲染，把 figure 写入图片文件。

对应地，py/visdom/init.py 中的 save_plotly_figure(figure, filepath, **kwargs) 在缺少 plotly 时会抛出 RuntimeError 提示安装命令；缺少 kaleido 时同样会捕获 write_image 抛出的 ValueError 并给出 pip install kaleido 的明确提示。输出格式由 filepath 的扩展名推断（png、svg、pdf 等），**kwargs 可透传 width、height、scale 等 write_image 参数。

对应 API 的完整用法参见 website/docs/api/basics.md 中的 vis.plotlyplot 与 vis.save_plotly_figure 小节，以及 README.md 中的相关示例。

验证安装是否成功

安装完成后，按以下三步验证环境是否就绪：

# 1. 检查已安装版本
python -c "import visdom; print(visdom.__version__)"

当前仓库的版本号记录在 py/visdom/VERSION，为 0.3.0。版本号由 py/visdom/__init__.py 读取该文件注入 __version__。

# 2. 启动服务器
visdom

# 3. 浏览器访问
http://localhost:8097

看到 Visdom dashboard 界面即表示安装与启动全部成功。服务端默认端口为 8097、默认主机名为 localhost、默认基础路径为 /、默认环境存储路径为 $HOME/.visdom/，这些默认值集中定义在 py/visdom/server/defaults.py。

深入理解 visdom 命令：它到底做了什么

visdom 命令与 python -m visdom.server 是等价的，二者都最终进入 py/visdom/server/run_server.py 的 download_scripts_and_run() 入口：

1. 下载前端脚本：先调用 build.download_scripts()，把 py/visdom/static/js/main.js 等前端静态资源准备到本地（首次启动时拉取）；
2. 解析命令行参数：main() 通过 argparse 解析全部启动选项；
3. 启动服务：start_server() 基于 Tornado 的 HTTPServer 绑定端口并进入事件循环，打印形如 You can navigate to http://localhost:8097/ 的访问地址。

其中端口校验值得留意：run_server.py 中的 valid_port() 只接受 1~65535 的整数，特意排除了端口 0（浏览器会以 ERR_UNSAFE_PORT 拒绝），同时拒绝布尔值、浮点数等隐式可转整形的输入。对应的单元测试见 py/tests/unit/run_server_cli.py。

常见安装问题排查

端口被占用

如果 8097 端口已被其他进程占用，可换端口启动：

visdom -port 8098

从源码角度看，即使不指定端口，_serve() 在捕获到 EADDRINUSE 错误时也会自动退避绑定一个空闲端口，并在日志中提示 Port ... is already in use, assigning a free port。因此"端口被占用"通常表现为启动日志中的警告而非直接崩溃。

安装权限不足

无管理员权限安装时，使用 --user 将包安装到当前用户目录：

pip install --user visdom

找不到 visdom 命令（Module not found）

安装成功但 visdom 命令不可用时，通常是 Python 的 scripts 目录不在 PATH 中。此时有两种处理方式：

# 方式一：把 Python scripts 目录加入 PATH
# 方式二：直接用模块方式运行
python -m visdom.server

进阶：服务端命令行选项总览

下表汇总了 visdom / python -m visdom.server 支持的核心命令行选项（参数解析见 py/visdom/server/run_server.py 的 main()，默认值见 py/visdom/server/defaults.py）：

选项	说明	默认值
-port	服务端口	8097
-hostname	服务主机名	localhost
-base_url	基础 URL 路径，必须以 / 开头且不以 / 结尾	/
-env_path	序列化会话（环境）的存储/加载路径	~/.visdom/
-logging_level	日志级别，接受文本（如 INFO）或数值（如 20）	INFO
-readonly	以只读模式启动服务	关闭
-enable_login	启用用户名/密码登录认证	关闭
-force_new_cookie	重置服务端安全 Cookie，使旧登录态失效（需配合 -enable_login）	关闭
-bind_local	仅允许本机（127.0.0.1）访问	关闭
-eager_data_loading	启动时预加载全部环境；默认按用户请求惰性加载	关闭
-save_interval	自动保存已变更环境的间隔秒数，0 关闭定时器	30
-save_threshold	环境累计更新达到该次数即提前保存，0 关闭	50
-ssl_certfile	SSL 证书文件路径（与 -ssl_keyfile 成对使用）	无（HTTP）
-ssl_keyfile	SSL 私钥文件路径（与 -ssl_certfile 成对使用）	无（HTTP）

另外还有 -use_frontend_client_polling，可让前端改用轮询而非 WebSocket 与服务端通信。base_url 的规范性检查（必须以 / 开头、不能以 / 结尾）由 run_server.py 在启动前断言完成。

关于自动保存机制：环境常驻内存，后台存储线程每 -save_interval 秒落盘一次，且一旦某个环境更新次数达到 -save_threshold 会立即提前保存；两个值同时设为 0 则恢复"仅手动保存 + 关闭时保存一次"的旧行为。更多细节可参考 website/docs/getting-started/command-line-options.md。

进阶：启用登录认证

默认情况下 Visdom 不带任何认证，任何能访问到该端口的人都可以查看和修改环境，因此共享或生产部署务必同时启用 -enable_login 与 -bind_local：

visdom -enable_login -bind_local

交互式启动时，服务端会在终端提示输入用户名和密码。若希望非交互式启动（例如从 bash 脚本或 Jupyter 启动），可通过环境变量注入凭据：

VISDOM_USERNAME=username
VISDOM_PASSWORD=password
VISDOM_USE_ENV_CREDENTIALS=1 visdom -enable_login

服务端实现会校验：设置了 VISDOM_USE_ENV_CREDENTIALS 但缺少用户名或密码时，直接报错退出；Cookie 文件缺失或使用 -force_new_cookie 时，可通过 VISDOM_COOKIE 环境变量提供 Cookie 值。这些逻辑都位于 py/visdom/server/run_server.py 的 main() 中。

进阶：HTTPS 支持

需要以 HTTPS 提供服务时，提供一对 SSL 证书与私钥即可。开发环境可先生成自签名证书：

# 生成自签名证书（仅用于开发）
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# 启动 HTTPS 服务
python -m visdom.server -ssl_certfile cert.pem -ssl_keyfile key.pem

然后通过 https://localhost:8097 访问。run_server.py 的 _build_ssl_context() 要求证书与私钥成对提供——只给其一会被视为配置错误直接抛 ValueError；路径不存在则抛 FileNotFoundError。Python 客户端连接时：

# 生产环境：使用真实 CA 签发的证书（默认校验）
vis = visdom.Visdom(server="https://myserver.com")

# 开发环境：自签名证书，关闭证书校验
vis = visdom.Visdom(server="https://localhost", ssl_verify=False)

注意：ssl_verify=False 会关闭证书验证，仅适用于带自签名证书的开发环境，严禁用于生产。

Python 客户端连接参数速览

visdom.Visdom() 构造函数（见 py/visdom/init.py）提供以下常用参数：

• server：服务端主机名（默认 'http://localhost'）
• port：服务端端口（默认 8097）
• base_url：基础 URL（默认 /）
• env：默认环境名，未显式指定 env 时写入该环境（默认 main）
• username / password：服务端开启 -enable_login 时使用的认证凭据（默认 None）
• proxies：协议到代理地址的映射字典（如 {"http": "foo.bar:3128"}），http_proxy_host/http_proxy_port 已废弃
• offline：离线模式，所有请求写入日志文件而不发往服务端，需同时设置 log_to_filename
• log_to_filename：把所有绘图/更新事件以追加方式记录到文件，之后可用 replay_log 回放
• use_incoming_socket：是否启用接收前端事件的 WebSocket（默认 True），关闭后无法注册回调
• use_preflight_checks：update='append' 或 store_history=True 前是否先询问窗口是否存在（默认 True）；设为 False 可把追加循环的请求数大约减半
• ssl_verify：HTTPS 下是否校验证书（默认 True，仅对 https:// 地址有效）

安装完成后可用下面的最小脚本做一次端到端冒烟验证（含 check_connection 连接检查）：

import visdom
import numpy as np

vis = visdom.Visdom()
assert vis.check_connection(timeout_seconds=3), "Could not connect to Visdom server"

vis.text('Hello, world!')
vis.image(np.ones((3, 10, 10)))

check_connection(timeout_seconds=0) 会在指定超时内轮询服务端连通性并返回布尔值；replay_log(log_filename) 则逐行解析日志文件、按序重放每个事件（见 py/visdom/init.py）。若已克隆仓库，还可以直接运行官方演示：

python example/demo.py

更多启动与使用细节可进一步阅读 website/docs/getting-started/usage.md（含 Hello World、环境管理、Jupyter 使用、离线模式与远程连接示例）。完成以上安装与验证后，即可通过 Python 客户端在浏览器中实时创建、组织并共享实验可视化。