企业官网建设流程全解析

• 数据可视化
• 前端

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

安装前置条件

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

• Python3.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）：

另外还有-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 客户端在浏览器中实时创建、组织并共享实验可视化。

• 数据可视化
• 前端