Pad.ws：将交互式白板转变为浏览器全功能IDE的完整指南

Pad.ws是一个创新的开发环境，它将交互式白板与全功能的IDE集成在浏览器中。该项目利用Excalidraw进行可视化设计，通过Coder提供云开发环境，并支持通过Docker Compose进行自托管部署。

什么是Pad.ws？重新定义开发工作流

在软件开发和构思的过程中，思维往往需要在抽象的可视化设计与具体的代码实现之间快速切换。Pad.ws 正是为了解决这一痛点而生，它不仅仅是一个白板工具，更是一个运行在浏览器中的完整开发环境（IDE）。
Pad.ws 的核心架构建立在两个强大的开源项目之上：

  • Excalidraw：负责提供直观、风格独特的手绘风格白板界面，允许用户自由绘制草图和可视化想法。
  • Coder：负责后端的云开发环境，提供强大的计算能力和完整的开发工具链。
    通过这两者的结合，Pad.ws 实现了从视觉构思到代码编写的无缝工作流。你可以在一个无限画布上绘制系统架构图，然后直接在画布旁打开终端或 VS Code 进行开发，无需在不同的应用程序或窗口之间来回切换。

核心功能深度解析

Pad.ws 并非简单的工具堆砌，而是针对现代开发者的实际需求进行了深度优化。以下是其核心功能的详细解析：

1. 交互式白板

这不仅仅是画图，而是一个可视化的思维空间。借助 Excalidraw 的强大功能，开发者可以：

  • 绘制、草绘和可视化各种想法。
  • 使用手绘风格的自然笔触，降低沟通门槛。
  • 在白板上直接组织复杂的信息结构。

2. 全功能 IDE

这是 Pad.ws 区别于传统白板工具的关键所在。它允许用户：

  • 直接在白板界面内访问终端。
  • 嵌入并使用 VS Code 进行代码编辑。
  • 在浏览器中获得接近桌面端的开发体验。

3. 浏览器友好的云端体验

打破硬件的束缚，Pad.ws 完全基于浏览器运行：

  • 支持从任何设备访问开发环境。
  • 依托云端的强大算力，不受本地设备性能限制。
  • 官方提供的托管实例目前免费提供 Ubuntu 开发环境，无需繁琐的本地配置。

4. 无缝工作流

设计是为了实现，而实现需要设计。Pad.ws 强调：

  • 在视觉构思和代码编写之间流畅切换。
  • 保持开发思路的连贯性，避免上下文切换带来的注意力分散。

5. 使用你熟悉的工具

为了尊重开发者的个人习惯，Pad.ws 提供了极高的灵活性：

  • 支持通过桌面客户端访问你的虚拟机（VM）。
  • 完美兼容 VS Code 和 Cursor 编辑器。
  • 允许开发者在不放弃现有高效工具的前提下享受白板带来的便利。
    Pad.ws Canvas IDE

自托管部署：从零开始搭建你的 Pad.ws 环境

虽然官方提供了在线托管服务，但对于追求数据隐私、定制化需求或希望在内网环境中使用的团队来说，自托管是最佳选择。以下是基于 Docker Compose 的详细部署指南。
重要提示：目前该仓库仍处于早期开发阶段。以下提供的 docker-compose.yml 配置主要用于开发和测试目的。虽然可以让你在本地主机上成功运行 Pad.ws，但在投入生产环境使用前，必须进行额外的安全配置。

前置准备

在开始之前，请确保你的环境满足以下基本要求：

  • 操作系统：Linux 主机（本教程基于 Ubuntu 测试通过）。
  • 容器环境：已安装 Docker 及 Docker Compose。如果尚未安装，请务必先完成 Docker 和 Docker Compose 的安装。

第一步：环境变量配置

配置是部署的基础，所有的敏感信息和连接参数都通过环境变量进行管理。

  1. 复制环境变量模板文件：
    在项目根目录下执行以下命令，将默认配置复制为实际使用的配置文件。

    cp .env.template .env
  2. 审查默认值：
    打开生成的 .env 文件，根据你的实际情况检查并修改其中的默认值。后续步骤中生成的关键信息（如密钥、ID等）都需要填入此文件。

第二步：部署 PostgreSQL 数据库

数据持久化是任何生产级应用的生命线，PostgreSQL 在此负责存储画布数据和系统配置。

  • 作用：确保整个部署过程中的数据持久化，包括所有的白板画布内容和应用配置。
  • 操作：使用提供的配置启动 PostgreSQL 容器。

    docker compose up -d postgres

    执行此命令后，Docker 将会在后台拉取镜像并启动数据库服务。

第三步：部署 Redis 缓存服务

为了提高系统响应速度和管理用户会话，引入了 Redis 作为内存数据存储。

  • 作用：作为内存数据存储，用于缓存处理和会话管理，确保用户登录状态的快速验证。
  • 安全配置：Redis 启用了密码认证机制以保障安全。
  • 操作：

    1. 启动 Redis 容器：

      docker compose up -d redis
    2. 关键配置：Redis 的密码必须在 .env 文件中通过 REDIS_PASSWORD 变量进行设置。请确保该密码足够复杂且未被泄露。

第四步：配置 Keycloak 身份认证

Keycloak 作为 OIDC（OpenID Connect）提供者，负责整个系统的访问控制和用户管理。这是确保开发环境安全的关键环节。

  1. 启动服务：

    docker compose up -d keycloak
  2. 访问管理控制台：
    在浏览器中打开 http://localhost:8080 访问 Keycloak 管理后台。
  3. 创建 Realm（域）：

    • 登录后，创建一个新的 Realm。
    • 命名建议使用具有辨识度的名称，例如 pad-ws。
  4. 创建 Client（客户端）：

    • 进入 Clients 页面，点击“Create client”。
    • Client ID：输入一个易于识别的 ID，例如 pad-ws-client。
    • Client Authentication：必须开启此选项。
    • Valid Redirect URIs：为了简化开发测试，可以添加 *，但在生产环境中应指定具体的 URL。
    • 保存配置。
  5. 获取凭据：

    • 在创建的 Client 详情页，点击“Credentials”标签页。
    • 复制 Client secret。
    • 更新环境变量：将获取到的信息填入 .env 文件：

      OIDC_REALM=your_oidc_realm
OIDC_CLIENT_ID=your_client_id 
OIDC_CLIENT_SECRET=your_client_secret
  6. 创建用户：

    • 导航到“Users”页面，点击“Create user”。
    • 填写用户详细信息。
    • 关键步骤：在用户详情页的“Email Verified”选项中，务必打钩。
    • 切换到“Credentials”标签页，为该用户设置登录密码。
  7. 配置 Audience（受众）：

    • 进入 Clients -> 选择你创建的 Client -> 点击“Client Scopes”。
    • 点击该 Client 专用 Scope（通常名为 [clientid]-dedicated）。
    • 点击“Configure a new mapper” -> 选择“Audience”。
    • 配置 Included Client Audience，使其与你的 Client ID 完全匹配。
    • 确保 Add to access token 选项处于“On”状态。

第五步：配置 Coder 开发环境

Coder 是提供云端开发能力的核心组件，需要精细配置以赋予其必要的权限。

  1. 获取 Docker 组 ID：
    为了让 Coder 能够调用 Docker，需要将其加入到宿主机的 Docker 组中。

    • 执行命令查询组 ID：

      getent group docker | cut -d: -f3
    • 更新环境变量：将得到的数字 ID 填入 .env 文件：

      DOCKER_GROUP_ID=your_docker_group_id
  2. 启动 Coder：

    docker compose up -d coder
  3. 初始化设置：

    • 在浏览器访问 http://localhost:7080 打开 Coder UI。
    • 首次登录时，创建一个管理员用户（例如用户名为 admin）。
  4. 创建模板：

    • 登录后，选择“Start from template”。
    • 选择基础镜像（例如 docker-containers 或简单的 Ubuntu 镜像）并根据需求进行配置。
  5. 获取 API Key：

    • 点击右上角的个人资料图片 -> 选择“Account” -> 进入“API Keys”页面。
    • 生成一个新的 Token。
    • 更新环境变量：将 Token 填入 .env：

      CODER_API_KEY=your_coder_api_key
  6. 获取模板 ID：

    • 访问 http://localhost:7080/api/v2/templates（可通过浏览器直接访问或使用 curl 命令）。
    • 找到你刚才创建的模板对应的 id 字段。
    • 更新环境变量：

      CODER_TEMPLATE_ID=your_coder_template_id

      示例值：85fb21ba-085b-47a6-9f4d-94ea979aaba9

  7. 获取默认组织 ID：

    • 访问 http://localhost:7080/api/v2/organizations。
    • 找到你的组织（通常是默认组织）对应的 id。
    • 更新环境变量：

      CODER_DEFAULT_ORGANIZATION=your_organization_id

      示例值：70f6af06-ef3a-4b4c-a663-c03c9ee423bb

  8. （可选）自定义工作区名称：

    • 如果你没有使用默认的工作区名称 ubuntu，则必须在 .env 文件中显式设置 CODER_WORKSPACE_NAME。

第六步：启动 Pad 应用

最后一步是启动 Pad.ws 的核心应用，这是一个基于 FastAPI 构建的应用，负责提供前端构建界面以及与 Coder 交互的后端 API。

  • 操作：

    1. 再次检查 .env 文件，确保所有上述步骤中提及的环境变量都已正确无误地填写。
    2. 启动 Pad 应用容器：

      docker compose up -d pad
  1. 访问应用：
    恭喜！如果一切配置正确，你现在可以在浏览器中访问 http://localhost:8000 并使用 Keycloak 中创建的用户登录到你自己部署的 Pad.ws 环境了。

常见问题与解决方案

为什么我在访问 localhost:8000 时无法登录？

请检查 Keycloak 的配置，特别是 Client 的 Valid Redirect URIs 是否包含你的访问地址，以及 Client Secret 是否正确填入了 Pad 应用的环境变量中。同时，确认 Keycloak 中的用户已勾选“Email Verified”。

Coder 容器启动失败或权限不足？

这通常是因为 DOCKER_GROUP_ID 配置错误。请确保你使用 getent group docker 命令获取的是宿主机上 docker 组的真实 GID，而不是容器内的 ID。

数据会丢失吗？

只要 PostgreSQL 容器的数据卷（Volume）配置正确且未被删除，你的画布数据和配置就是持久化的。在进行 docker compose down 操作时，请小心不要使用 -v 参数，除非你确实想清空数据。

我可以在生产环境中使用这个配置吗？

目前的 docker-compose.yml 仅用于开发和测试。在生产环境中使用前，你需要对网络安全、HTTPS 配置、密钥管理等方面进行加固。

总结

Pad.ws 通过巧妙地结合 Excalidraw 的可视化能力和 Coder 的强大开发环境，为开发者提供了一个前所未有的混合型工作空间。无论是在线体验还是本地自托管，它都展示了浏览器作为开发平台的巨大潜力。通过上述详尽的部署指南，你完全可以搭建一个属于自己的、集绘图与编码于一体的私有化开发环境。