企业官网建设流程全解析

• 数据可视化
• 前端

Visdom 是一款面向 AI/ML 实验的可视化工具，它由 Python/Tornado 后端、React 前端与 Lua/Python 双客户端组成。本文以仓库根目录的 CONTRIBUTING.md 为骨架，完整讲解如何排查常见使用问题、如何报告 Bug、如何提交 Pull Request，并深入 Python（pytest）与前端（Playwright）两套测试体系的架构与实战用法。读完本文，你将掌握一条从"遇到问题"到"提交被合入的代码"的完整贡献路径，并能在当前仓库源码中定位到每一步对应的实现文件。

一、先学会排障：用 Issue 清单理解 Visdom 的运行机制

贡献者最常见的起点不是写代码，而是先理解问题。CONTRIBUTING.md 把高频问题整理成了一张排障清单，同时也揭示了 Visdom 的核心运行架构：Python 客户端负责构造数据 → 经 WebSocket 发送给 Tornado 服务器 → 服务器将 JSON 结构交给前端 Plotly 渲染。

1.1 无法连接 Visdom 服务器

这是最高频的问题。排查链路如下：

1. 确认服务器是否在运行：通过python -m visdom.server启动，然后尝试重启。该命令对应的实现入口在 py/visdom/server/main.py，它会调用 run_server.py 中的启动逻辑。
2. 确认网络未被阻断：防火墙可能拦截了浏览器与服务器之间的流量，此时可通过服务器启动参数-proxy指定代理；也可以在本地~/.ssh/config中为远程服务器配置 SSH 隧道转发：

   LocalForward 127.0.0.1:8097 127.0.0.1:8097

3. 确认端口未被占用：部分用户反馈执行sudo ufw allow 8097可以放行被防火墙拦截的 8097 端口。

值得注意的是，Visdom 的默认端口 8097 同样体现在测试基建中：例如 playwright.config.js 的 webServer 配置使用visdom -port 8098 -env_path /tmp启动独立实例，而 py/tests/conftest.py 中appfixture 默认构造Application(port=8097, ...)。

1.2 浏览器出现蓝屏但看不到可视化内容

蓝屏通常意味着前端 JavaScript 依赖没有加载成功，这在部分网络环境下是常见问题。排查方式：

1. 在 Chrome 中点击View → Developer → JavaScript Console，检查是否存在与缺失 JS 依赖相关的报错。
2. 若确认依赖缺失，进入已安装的visdom包目录（例如/home/$USERNAME/$ANACONDA_FOLDER/lib/python$PYTHON_VERSION/site-packages/visdom-$VISDOM_VERSION-py$PYTHON_VERSION.egg，路径变量取决于你的安装方式，从源码安装时目录可能不同）。
3. 查看仓库根目录的 download.sh 脚本——它会下载 Plotly、MathJax、SJCL 等前端资源到py/static/js与py/static/css等目录，你可以直接执行该脚本，或按脚本内容手动下载全部资源。
4. 重启 Visdom 服务器，再次打开 JavaScript Console 确认依赖已全部就位。

从源码结构看，download.sh 下载的plotly.min.js、mathjax-tex-mml-svg.js等资源正是前端渲染与公式显示所依赖的运行时库，最终会被 setup.py 通过package_data={"visdom": ["static/*.*", "static/**/*", ...]}打包进发行版。

1.3 想要一个现有 API 之外的绘图特性

Visdom 的可视化能力建立在 Plotly 之上：客户端代码先构造一个 JSON 结构，再由服务器把该结构交给 Plotly 渲染。这意味着"只要输入正确，Visdom 就能展示 Plotly 支持的任何可视化"——但 Visdom 只暴露了其中最常见的部分。

如果你需要某个未暴露的特性，官方态度是"欢迎直接动手改造客户端"：

• 修改产生数据结构的客户端代码，位置在 py/visdom/init.py；

• 每种绘图类型的全部可用选项可以参考 Plotly 官方手册（Python 版）；

• 甚至可以从零构造自己的绘图数据结构，然后直接调用_send方法把它发送给 Visdom 服务器。_send的当前实现位于 py/visdom/init.py，签名形如：

  def _send(self, msg, endpoint="events", quiet=False, from_log=False, ...):

  它是客户端与服务器之间所有消息（默认走events端点）的统一出口，理解它有助于定位"数据是如何从 Python 到达前端"的完整链路。

1.4 想使用 pip 版本尚未包含的新特性

最新的特性往往只在源码仓库中。从源码安装的方式：

# 先卸载已安装版本，再以可编辑模式安装 pip uninstall visdom && pip install -e .

本地开发注意事项：执行python -m visdom.server时，Python 可能仍会导入site-packages里旧版本的visdom包，而不是你 checkout 出来的源码。此时会出现"前端编译成功、main.js已更新、服务器正常重启、但 UI 仍旧是老行为"的迷惑现象。

验证当前实际加载的源码：

python -c "import visdom; print(visdom.__file__)"

输出路径应指向你的本地仓库而非site-packages。若需要手动优先本地源码：

export PYTHONPATH=$PWD/py:$PYTHONPATH

部分 pip 安装场景下可编辑安装无法正确链接模块，此时可退而使用python setup.py install。关于 Python 版本约束，setup.py 中python_requires=">=3.12"明确写明了当前仓库要求 Python 3.12 及以上。

二、如何提交一份高质量 Bug 报告

找到问题后，一份可复现的报告能极大加速定位。CONTRIBUTING.md 要求 Bug 报告中必须包含以下三要素：

1. Visdom 服务器输出的错误信息：直接从终端复制粘贴；
2. JavaScript Console 输出的错误信息（如有）：在 Chrome 中通过View → Developer → JavaScript Console查看并粘贴警告或错误；
3. 运行平台信息：操作系统、浏览器、Visdom 版本。

在提交前，请先翻阅 Issue 列表确认是否已有相同问题及解决方案；同时请理解，Visdom 是维护者业余时间维护的项目，没有专职工程师，请求无法全部即时响应。

三、贡献者行为准则：首次贡献者与 AI 辅助编码

仓库对贡献者提出了两条明确的"软性"规范：

• 首次贡献者：建议从入门级 issue 开始，避免一开始就接手涉及大规模文件改动或重大代码重构的任务，保持初始贡献聚焦、范围可控，便于熟悉代码库并通过评审。
• AI 辅助编码：欢迎使用 AI 工具协助编写、调试或理解代码，但只有在你完全理解改动作用、并能逐行解释每一处改动时才应提交 PR。盲目复制粘贴无法解释、无法调试的 AI 生成代码是不被允许的——贡献者对自己提交代码的正确性与可维护性负全责。

四、Pull Request 流程全解

仓库积极欢迎 PR，提交前请逐条核对以下清单：

1. Fork 仓库，并从dev分支创建你的工作分支；
2. 新增代码必须有对应测试（Python 测试规范见下一节）；
3. 若改动了 API，同步更新文档；
4. 确保 Lua 与 Python 两套接口保持同步——仓库中 th/（Lua 侧）与 py/visdom/（Python 侧）共同面向同一套服务器协议，这是 Visdom 双客户端架构的特殊要求；
5. 若改动js/目录，需提交 React 编译后的main.js（详见"UI 贡献"一节，GitHub Action "Update Static JS Files" 会在你创建分支后自动构建并提交main.js与main.js.map）；
6. 为新特性添加 demo（见仓库 example/ 目录），并确保 demo 可运行；
7. 保证代码通过 lint：
   • JavaScript：npm lint
   • Python：black py（安装pip install black==23.1）
   • 可在每次git commit前自动执行：pre-commit install
8. 若尚未签署，完成 Contributor License Agreement（CLA）。

五、Python 测试体系：py/tests 的架构与用法

Visdom 的 Python 测试套件使用 pytest 下。其设计宗旨是封闭（hermetic）：不需要运行真实的 Visdom 服务器，也没有任何测试触碰网络。由于 Visdom 要求 Python 3.12+，测试也应运行在 3.12 及以上环境。

5.1 运行测试

pip install -e . # 安装 visdom pip install -r test-requirements.txt # 安装 pytest 及测试依赖 pytest # 运行整套测试 pytest -m "not server" # CI 实际运行的命令（排除需要外部服务器的用例）

测试发现规则配置在 pyproject.toml 中：testpaths = ["py/tests"]限定只收集py/tests下的用例（仓库根目录的零散test_*.py脚本会被忽略），因此从仓库任意位置执行pytest都能自动发现套件，无需传入路径。

开发期间的常用收窄方式：

pytest py/tests/unit # 快速子集：无 HTTP，纯逻辑 pytest py/tests/unit/window_builder.py # 单个文件 pytest -k window_builder # 按名称匹配 pytest -x --lf # 首个失败即停，随后只重跑失败项

unit、integration、slow、server四个 marker 均在 pyproject.toml 中注册，可用-m选择；addopts = "-ra -q"已默认开启-q，再传-q会隐藏汇总行，如需 pytest 完整默认输出可加-o addopts=""。

5.2 测试目录结构与新增测试的规范

目录结构如下：

py/tests/ conftest.py # 共享 fixtures，自动加载 testutils/ # 可导入的辅助代码——永远不会被当作测试收集 unit/ # 纯逻辑：不构造 Application，除 tmp_path 外无 I/O integration/ # 进程内 Application、真实 HTTP 或 handler 分发

新增测试时的三条硬性规范：

1. 文件放哪、叫什么：按依赖选择unit/或integration/；文件命名用unit/window_builder.py而非unit/test_window_builder.py（目录名已经说明是测试），但测试函数仍必须以test_前缀命名，否则 pytest 不会执行。
2. 优先使用普通函数：写成def test_*()函数。pytest 无法向unittest.TestCase方法注入 fixture，所以TestCase无法使用 conftest.py 中的任何共享 fixture，也无法使用@pytest.mark.parametrize。唯一例外是需要真实 HTTP 往返的测试：继承testutils.VisdomHTTPTestCase（定义于 py/tests/testutils/http.py），它在临时端口上进程内启动 Tornado app，仍然保持封闭性。
3. 外部服务器标记：需要外部启动的服务器才能运行的测试必须标注@pytest.mark.server，以便 CI 通过-m "not server"排除。当前套件中没有任何用例需要它。

5.3 共享 fixtures 与测试依赖

py/tests/conftest.py 提供的共享 fixture 揭示了测试如何逼近真实运行环境：

• env_path：临时环境目录（基于tmp_path）；
• store/spy_store：分别提供真实的JSONStore与记录服务器调用的SpyStore（见 py/tests/testutils/fakes.py）；
• app/app_factory：构造进程内的Application（默认端口 8097），只记录端口不真正绑定，因此可并行构造；
• inline_executor：把IOLoop.current().run_in_executor调用改为线程内立即执行，用于断言自动保存等异步调度行为。

测试依赖清单见 test-requirements.txt，包含 pytest、matplotlib、numpy、torch、lightning、scikit-learn、xgboost 等——这与 py/visdom/loggers/ 下各框架 logger 的测试需求一一对应（如keras.py、lightning.py、sklearn.py、xgboost.py）。

六、UI 贡献：React 前端构建与 Playwright 端到端测试

Visdom 前端基于React构建，源码位于 js/ 目录。一个关键术语澄清：UI 中的 "Pane" 就是 Python/Lua API 里所称的 "window"。由于前端需要编译，所有 JS 改动都要走构建流程。

6.1 前端构建：yarn 与 npm 二选一

# yarn 方式 cd /path/to/visdom yarn # 安装 node 依赖 yarn run build # 构建 js

# npm 方式 cd /path/to/visdom npm install # 安装 node 依赖 npm run build # 构建 js

这两条命令分别对应 package.json 中的脚本与 webpack 配置（webpack.dev.js、webpack.prod.js、webpack.common.js）：npm run build走生产构建，npm run dev则是带 watch 的开发模式。提交 PR 时，官方建议让 GitHub Action "Update Static JS Files" 来编译，以保证构建一致性——该 Action 会在你创建的任何分支上检测到 JS 文件变更后自动构建，并把生成的main.js与main.js.map提交回分支（对应 py/visdom/static/js/ 下的产物）。

Demo 与 UI 测试依赖部分 Python 包，请先安装：

pip install -r test-requirements.txt

6.2 Playwright 测试矩阵：端到端与视觉回归

项目使用 Playwright，涵盖基础功能、图片、文本、属性、导出、上传、并行坐标等多个方面。若你新增或修改了函数，建议同步调整或补充测试。

Playwright UI 模式：

npx playwright install chromium # 首次安装浏览器 npm run build # 或 npm run dev，编译前端 # 确保 8098 端口可用——Playwright 会自动启动一个隔离的 Visdom 服务器 npm run test:gui # 打开 UI 并选择要检查的 spec

CLI 模式：

npx playwright install chromium npm run build # 或 npm run dev npm test # 运行 WebSocket 套件 npm run test:polling # 用前端轮询方式运行同一套功能测试

视觉回归测试：

npm run test:init # UI 改动前，先生成基线截图 npm run test:visual # 改动构建完成后，与基线对比

这些命令与 package.json 中的 scripts 一一对应，并分别使用独立的 Playwright 配置（playwright.config.js、playwright.polling.config.js、playwright.init.config.js、playwright.visual.config.js）。从配置可见：默认 WebSocket 套件通过 webServer 自动执行visdom -port 8098 -env_path /tmp（不复用已有服务器、不包含视觉回归 spec）；轮询套件则以-use_frontend_client_polling启动 Visdom——该参数在 py/visdom/server/run_server.py 的命令行解析中注册，用于让前端通过轮询而非 WebSocket 获取更新，从而覆盖两种传输通道。

七、编码风格与许可协议

• Lua：使用 3 空格缩进，不用 tab；
• Python：遵循 PEP 8；
• 行宽：80 字符；
• License：贡献即表示同意你的贡献遵循仓库根目录 LICENSE 的条款（Apache-2.0）。

总结

一条完整的 Visdom 贡献链路可以这样概括：先借 Issue 排障清单吃透"Python 客户端 → Tornado 服务器 → Plotly 渲染"的核心架构；按三要素模板提交可复现的 Bug 报告；认领入门 issue、在dev分支上做小而聚焦的改动；Python 侧改动落入 py/tests/ 的unit/与integration/目录并跑通 pytest，前端改动经 webpack 构建后用 Playwright 四套配置验证 WebSocket 与轮询两条通道及视觉回归；最后经 lint、文档与 Lua/Python 接口同步检查后提交 PR。每一条规则背后都有当前仓库的配置与实现文件可查证，这正是 Visdom 作为开源项目"易贡献、可验证"的工程化体现。

• 数据可视化
• 前端