写这篇教程之前先说个事WorkBuddy 安装本身不难难的是很多人卡在环境准备上。它不是那种双击 setup.exe 就完事的软件整个产品跑在 Docker 容器里所以“装 WorkBuddy”这件事拆开来看就是“装好 Docker 环境 拉镜像跑容器”两步。Windows 要绕一下 WSL2macOS 相对省心但有芯片架构的讲究。这篇文章我把两个平台的完整步骤都过一遍包括参数解释、踩坑记录、常见问题速查表照着做基本能一次跑通。1. 安装前的整体设计与核心思路1.1 WorkBuddy 的形态决定了安装方式如果你用过 CodeBuddy 这类 AI 开发助手再看 WorkBuddy 会有种熟悉感但定位明显更宽。WorkBuddy 更像是把大模型能力接入到日常工作流里的一个智能工作台可以做文档处理、任务编排、知识库问答也能挂自定义 skill。它背后是云端/本地混合的模型服务但客户端这边为了保证跨平台一致性、降低依赖冲突选择了容器化分发。容器化意味着什么意味着你不需要在本机装一堆 Python 依赖、Node 环境、模型权重文件所有运行环境都被打包在镜像里。对使用者来说这是好事但对第一次接触 Docker 的人来说门槛反而在“Docker 怎么装”。我见过不少同事卡在 Docker Desktop 启动失败这一步最后发现是 WSL2 没开或者虚拟化没开。所以这篇文章会把环境准备讲得特别细因为这里出问题的概率最高。1.2 Windows 和 macOS 在安装路径上的本质区别Windows 下跑 Linux 容器最优雅的方式是 WSL2。WorkBuddy 的镜像基本是 Linux 镜像而 Docker Desktop 在 Windows 上有两种引擎Windows 容器引擎和 Linux 容器引擎。WorkBuddy 走的是 Linux 容器所以 Windows 上必须有一个能跑 Linux 内核的环境。WSL2 本质是一个轻量虚拟机微软内置集成比传统 Hyper-V 方案更省资源、启动更快对普通用户也更友好。macOS 这边不一样它本身就是 Unix 系统Docker Desktop 直接跑在原生内核上不需要 WSL 这一层。但 Apple Silicon 和 Intel 芯片的镜像架构不同下载 Docker Desktop 时要选对版本这个我在第 3 章细说。一句话总结Windows 的难点在 WSL2 配置macOS 的难点在架构选择和系统权限。1.3 硬件与软件环境的硬性门槛先看最低配置再决定要不要升级机器。我建议的内存底线是 16GB8GB 能跑但会很紧张因为 Docker Desktop 本身占几百 MBWSL2 虚拟机再占一部分WorkBuddy 容器启动后又要吃内存三块加起来轻松到 4~6GB。如果你平时还要开浏览器、微信、IDE8GB 会明显卡。项目最低要求推荐配置操作系统Windows 10 2004 / macOS 12Windows 11 / macOS 14CPUx86_64Intel/AMD或 arm64Apple Silicon 或 Intel 8 代以上内存8GB16GB 以上磁盘20GB 可用空间固态硬盘50GB 以上虚拟化BIOS 中开启 VT-x/AMD-V同上网络能访问 Docker Hub 或镜像加速服务国内网络建议配镜像加速Windows 用户可以打开任务管理器切到“性能”页看 CPU 一栏有没有显示“虚拟化: 已启用”。如果显示未启用说明 BIOS 里没开需要重启进 BIOS 找 Intel Virtualization Technology / SVM Mode 打开。这一步不做后面 WSL2 会直接报错。1.4 安装前需要准备的账号与工具清单工具方面很简单Windows 用户建议装一个 Windows TerminalmacOS 用户用自带终端就行。账号方面需要准备一个腾讯云账号或者你所在企业提供的企业身份账号。首次登录 WorkBuddy 工作台时会要求绑定身份个人使用就注册一个账号企业使用一般走企业 SSO 登录需要在管理后台提前开通权限。另外我强烈建议在开始安装之前先去 WorkBuddy 官方文档页面把镜像地址、默认端口、数据目录这些信息复制出来。不同版本镜像名可能不一样端口也可能调整教程里的命令是通用参考实际操作以官方文档给出来的为准。这个习惯能帮你省掉后面很多排查时间。2. Windows 平台完整安装教程2.1 第一步安装并配置 WSL2 子系统如果你的 Windows 是 Windows 10 2004 及以上版本最简单的方式是用管理员身份打开 PowerShell 或 Windows Terminal直接执行一条命令wsl --install -d Ubuntu-22.04这条命令会做三件事启用“适用于 Linux 的 Windows 子系统”功能、启用“虚拟机平台”功能、下载并安装 Ubuntu 22.04 发行版。安装完成后系统会提示重启重启后继续。重启后第一次进入 Ubuntu 终端会让你设置一个 Linux 用户名和密码。这里要注意用户名和 Windows 用户名可以不一样这个密码是 Linux 子系统里用 sudo 命令时要输入的和 Windows 登录密码无关。很多人在这里顺手输错了几次后面 sudo 一直报错挺影响心情。安装完之后在 PowerShell 里执行下面命令确认版本wsl -l -v你会看到类似这样的输出Ubuntu 那行的 VERSION 列应该是 2如果显示 1说明系统把发行版建成了 WSL1执行wsl --set-version Ubuntu-22.04 2切换过来。再执行一次wsl --update更新内核保证内核版本比较新。到这里WSL2 环境就绪。如果你用的 Windows 版本比较老wsl --install命令可能不存在或报错那就走传统路径控制面板 - 程序和功能 - 启用或关闭 Windows 功能勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”重启后去微软官网下载 WSL2 内核更新包安装最后去 Microsoft Store 装一个 Ubuntu。这条路多一点手动操作但结果是等价的。2.2 第二步安装 Docker Desktop 并切换引擎去 Docker 官网下载 Windows 版 Docker Desktop。安装过程中有一页问你是用 Windows 容器还是 Linux 容器保持默认的“Use WSL 2 based engine”勾选状态就行。安装完成后先别急着用打开 Docker Desktop进 Settings - Resources - WSL Integration把 Ubuntu 的开关打开。这一步的意义是让 Docker 命令可以直接在 Ubuntu 终端里使用不打开这个开关你在 Ubuntu 里敲 docker 命令会报 command not found。到这里先验证一下环境docker --version docker compose version能正常输出版本号说明 Docker 环境没问题。如果 Docker Desktop 一直卡在 Starting先别急着重装大概率是 WSL2 没配置好或者 BIOS 虚拟化没开。这时候把 2.1 节的步骤重新检查一遍执行wsl --shutdown再重启 Docker Desktop通常能解决。停一下这里插一个实际问题Docker Desktop 在某些公司电脑上可能因为 IT 策略限制无法正常安装或联网。如果是这种情况可以看看你们公司内部是不是已经有统一的容器环境或者联系 IT 开通权限没必要自己折腾替换方案。2.3 第三步拉取 WorkBuddy 镜像并启动容器这一节是核心操作。先确认文档给的镜像地址例如它可能长这样实际以官方为准docker pull ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest拉取的过程视网络情况而定如果速度很慢可以看 5.4 节配置镜像加速。镜像拉下来之后用类似下面的命令启动容器docker run -d \ --name workbuddy \ --restart unless-stopped \ -p 21000:8080 \ -v C:\Users\你的用户名\workbuddy_data:/app/data \ ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest逐个解释一下参数后面排查问题会用得上-d后台运行日志不会在当前终端刷屏。--name workbuddy给容器起个固定名字后面 docker logs、docker stop 都用这个名字操作。--restart unless-stoppedDocker 服务重启或系统重启时自动拉起容器除非你手动 stop。这个参数强烈建议加否则电脑重启后 WorkBuddy 不会自己爬起来。-p 21000:8080端口映射。左边是宿主机端口右边是容器内部服务端口。WorkBuddy 在容器里监听 8080但你通过宿主机的 21000 访问。左边端口可以自己改比如改成 18080只要不和你其他服务冲突就行。-v C:\Users\你的用户名\workbuddy_data:/app/data数据卷挂载。左边是 Windows 宿主机上的目录右边是容器里的数据目录。把数据目录暴露出来以后升级容器、删掉重建技能、配置、知识库文件都还在。启动之后马上验证一下docker ps docker logs -f workbuddydocker ps看 workbuddy 的 STATUS 是不是 Updocker logs看启动日志有没有报错。看到类似“服务已启动”或监听端口输出的日志基本就成了。2.4 第四步打开浏览器完成初始化登录容器起来后打开浏览器访问http://localhost:21000。首次访问会进入初始化页面流程一般是确认服务条款 - 选择登录方式 - 绑定账号。如果你是企业用户会跳转到企业 SSO 登录页这里需要确保你的账号已经在 WorkBuddy 管理后台被授权否则登录后可能提示无权限。登录成功后进入工作台首页左边是导航右边是聊天/任务输入框整体布局和一些 AI 工作台产品很像。到这里 Windows 平台的安装就算完成了。如果打开浏览器后一直转圈或者页面打不开八成是端口映射或容器启动问题直接去 5.3 节查端口、5.2 节看 Docker 状态。2.5 Windows 安装全流程检查清单与踩坑提示把整个 Windows 流程压缩成一份检查清单方便你对着看检查项预期结果失败时的方向BIOS 虚拟化任务管理器显示“已启用”进 BIOS 开启 VT-x/AMD-VWSL2 功能wsl -l -v 显示 VERSION 2wsl --set-version 或 --updateDocker Desktop任务栏图标正常状态为 Runningwsl --shutdown 后重启 DockerWSL 集成Ubuntu 终端能执行 docker --versionSettings - WSL Integration 勾选容器状态docker ps 中 workbuddy 为 Updocker logs 查日志页面访问localhost:21000 能打开登录页检查端口映射和 Windows 防火墙Windows 上最容易忽略的是防火墙弹窗。第一次启动容器时Windows 安全中心可能会弹一个允许 Docker Desktop 在网络上通信的提示如果你点了取消后面局域网访问会失败localhost 访问有时也不正常。没弹的话手动去防火墙里放行 Docker 相关进程或者直接确认网络类型是“专用网络”能省不少麻烦。3. macOS 平台完整安装教程3.1 第一步确认芯片架构并安装 Docker DesktopmacOS 安装 Windows 相对省心但第一步要先搞清楚你机器是 Apple Silicon 还是 Intel。点击左上角苹果标志 - 关于本机处理器那栏写着 M1、M2、M3、M4 都是 Apple Silicon写着 Intel 就是 Intel 芯片。这个区别很重要因为 Docker Desktop 分两个安装包Intel 芯片下载 x86_64 版本Apple Silicon 下载 arm64 版本。下错版本也能装但运行效率会受影响甚至可能启动报错。下载完成后打开 dmg 文件把 Docker.app 拖进 Applications 文件夹完成安装。第一次打开 Docker.app 时macOS 可能会弹一个“无法打开因为无法验证开发者”之类的提示。这种情况不用慌去系统设置 - 隐私与安全性往下滚动找到“仍要打开”的按钮确认一次就行了。这是 macOS Gatekeeper 的正常拦截逻辑不是什么安装包损坏。3.2 第二步Docker Desktop 基础设置与内存分配打开 Docker Desktop右上角设置图标点进去。重点关注 Resources 页面内存建议设置到 4GB ~ 8GBCPU 给 4 核。如果机器只有 8GB 内存Docker Desktop 里设置 4GB 就好再多会影响系统流畅度。Apple Silicon 机器上 Docker 性能一般都不错磁盘类型默认的 VirtioFS 就好。另外在设置 - 资源 - 文件共享里如果你准备把 macOS 的某个目录挂载进容器做数据存储需要把对应目录加进去。这个操作在 Windows 上不用专门设置但 macOS 的沙箱机制会导致 Docker Desktop 默认访问不到某些目录提前加进去能避免后面启动容器时提示权限不足。配置完先重启一次 Docker Desktop让它加载新配置。然后终端里验证一次docker --version docker compose version3.3 第三步拉取镜像、启动容器与首次登录macOS 下的拉取和启动命令和 Windows 几乎一样只有挂载目录的路径不一样。示例docker pull ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest docker run -d \ --name workbuddy \ --restart unless-stopped \ -p 21000:8080 \ -v $HOME/workbuddy_data:/app/data \ ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest这里用$HOME变量代替了完整路径不管你用户名是什么都能正确指向当前用户目录。启动后用docker logs -f workbuddy观察输出看到正常启动日志后浏览器访问http://localhost:21000后续登录流程和 Windows 完全一样。Apple Silicon 的用户可以注意一下日志里有没有提示平台兼容性。如果镜像本身是 x86_64 架构Docker 可以通过 Rosetta 模拟运行但性能会有损耗。假如你发现日志里出现类似“architecture”的警告可以看看官方有没有发布 arm64 版本的镜像如果有就优先用 arm64 版本。3.4 macOS 安装中的细节与效率技巧macOS 有一个 Windows 用户体会不到的便利因为 macOS 本身就有完整的 Unix 环境很多排查命令用起来更顺手。比如容器起来后想快速测试端口通不通一条curl -I http://localhost:21000就能看到 HTTP 状态码不用额外装工具。资源占用方面macOS 下的 Docker Desktop 在空闲时会占用不少内存这并不全是 WorkBuddy 的问题Docker 本身的守护进程和虚拟机都有开销。如果你比较介意可以在 Docker Desktop 设置里把“自动启动”关掉平时不用 WorkBuddy 时手动退出 Docker Desktop能释放不少内存。另外启动容器时可以加--memory4g限制容器可用内存避免模型任务把整台机器的内存吃满。但注意如果后续发现 WorkBuddy 功能异常比如导出大文件时卡死很可能是内存限制太紧调高或去掉限制再试。安装时还有一个容易忽略的坑如果之前机器上装过旧版 Docker Desktop升级大版本后可能会有残留配置导致启动失败。稳妥的办法是先把旧版彻底卸载再装新版。卸载时别只用把 App 拖进废纸篓最好用官方卸载流程不然残留的 vm 文件和配置会占空间也可能导致异常。4. 安装后的基础配置与自定义4.1 数据持久化与迁移为什么我前面强调一定要挂载数据卷因为容器是一个可随时销毁重建的运行体。如果数据全存在容器内部哪天你执行docker rm workbuddy里面的技能配置、自定义指令、知识库数据全部跟着消失。而挂载了数据卷之后这些内容都存在宿主机的workbuddy_data目录里容器删了、镜像更新了数据都还在。备份也很简单Windows 下直接把C:\Users\你的用户名\workbuddy_data压缩一份macOS 下把~/workbuddy_data压缩一份。换电脑时新机器装好 Docker 和 WorkBuddy 镜像后把备份目录恢复过去再启动容器数据和配置就回来了。4.2 skill 的加载与自定义指令推荐WorkBuddy 支持 skill 机制也就是把一些高频指令封装成可复用的技能。不同版本对 skill 的加载方式不太一样有的版本可以直接在工作台界面里导入有的版本需要把 skill 文件放到挂载出来的数据目录。具体以官方文档为准但大方向是通用的。这里分享几个我在实际使用中觉得比较实用的自定义指令方向一个是“会议纪要整理”把语音转写的文本丢进去让它按议题、结论、待办事项输出结构化纪要另一个是“周报生成”把这一周的工作流水记录贴进去让它自动归纳成周报还有一个是“文档审阅”让它在不改动原文的前提下帮你标记逻辑问题和表述冗余。这些指令都不复杂核心在于把你反复要做的 prompt 沉淀下来变成复用性强的 skill 文件。技能文件一般有固定的模板格式里面包含描述、输入参数和指令模板。写好后放到数据目录对应的 skills 子目录里重启 WorkBuddy 容器就能在工作台里看到新技能。如果你的团队有公共技能库也可以把技能文件上传到团队空间里共享。4.3 WorkBuddy 升级与容器重建容器化方案升级非常简单核心三步拉新镜像、删旧容器、用新镜像重建容器。命令如下docker pull ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest docker rm -f workbuddy docker run -d \ --name workbuddy \ --restart unless-stopped \ -p 21000:8080 \ -v C:\Users\你的用户名\workbuddy_data:/app/data \ ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest只要挂载目录没变升级后所有数据都还在。不过升级前建议先看一眼官方更新日志确认新版本有没有破坏性变更比如默认端口变化、API 接口调整、skill 格式不兼容之类的。我吃过这个亏某个版本更新后旧格式的技能文件全部失效排查半天才发现是格式规范改了。4.4 局域网访问与团队共享默认情况下 WorkBuddy 监听在容器的 8080 端口映射到宿主机的 21000 端口所以你在本机能访问。如果同一个办公室的同事也想访问你机器上跑的 WorkBuddy那就需要让容器监听所有网络接口。一般 Docker 默认就绑定了所有接口所以同事在浏览器里输入你机器的局域网 IP 加冒号加 21000比如http://192.168.1.100:21000理论上就能访问。Windows 下这一步容易卡在防火墙macOS 下也会弹一个是否允许 Docker 接收传入连接的系统询问要点允许。这里强调一个安全提醒局域网共享没问题但不要把这个端口映射到公网暴露开放因为 Web 界面大概率没有内置的访问控制暴露到公网等于把工作台敞开给别人。如果有远程访问需求建议走团队内网或官方推荐的网关方案。5. 常见问题与排查技巧实录5.1 高频问题速查表问题可能原因解决方法Docker Desktop 一直 StartingWSL2 未正确配置wsl --shutdown重启 Docker Desktopwsl --install 报 0x80370102BIOS 虚拟化未开启进 BIOS 开启 VT-x/AMD-V容器启动后立即退出镜像不兼容或资源不足docker logs 查日志调整内存浏览器打不开 localhost:21000端口映射错误或容器未运行docker ps 检查确认 -p 参数镜像拉取非常慢网络到 Docker Hub 不稳定配置国内镜像加速器登录页打不开或跳转失败系统时间不对或 DNS 问题校准时间、刷新 DNS、换浏览器Windows 防火墙阻止访问首次弹窗点了取消手动放行 Docker 进程或端口这张表里的问题我基本都遇到过下面的小节展开讲最关键的排查套路。5.2 Docker 起不来先从这几个方向查Docker Desktop 在 Windows 上卡在启动页大概率不是 Docker 本身的问题而是它依赖的 WSL2 环境出问题了。最常用的三连操作是先右键退出 Docker Desktop然后在管理员 PowerShell 里执行wsl --shutdown等十几秒后再重新打开 Docker Desktop。这招能解决八成启动卡住的情况原理是清理掉 WSL2 的残留进程和会话。如果还不行检查 C 盘空间。WSL2 默认把虚拟磁盘放在 C 盘虚拟磁盘会随着使用越变越大C 盘满了之后 Docker Desktop 会各种奇怪地启动失败。清理完磁盘后用wsl --manage Ubuntu-22.04 --set-sparse true把虚拟磁盘变成稀疏模式能有效控制大小。macOS 上 Docker 起不来优先看 Docker Desktop 自带的诊断信息。点击菜单栏 Docker 图标 - Troubleshoot - Get support里面能导出一份诊断日志。大部分情况下重启一次 Docker Desktop 就好实在不行就重置 Docker 的虚拟环境Troubleshoot - Reset to factory defaults。注意这会把所有镜像和容器清掉如果有重要数据先备份。5.3 端口占用与冲突处理-p 21000:8080这个映射中21000 是宿主机端口如果这个端口已经被其他程序占用容器启动会报错提示 bind: address already in use。Windows 下用下面命令查端口占用netstat -ano | findstr :21000看到输出后最后一列是 PID用任务管理器找到这个 PID 对应的进程结束它即可。或者用一行命令直接强制结束taskkill /PID 你的PID /FmacOS 下的命令是lsof -i :21000 kill -9 你的PID如果你不想动占用端口的程序更简单的办法是换个映射端口把-p 21000:8080改成-p 18080:8080重新用新端口访问就行。这个改动成本和风险都很低在本地开发环境是最快的解决路径。5.4 镜像拉取慢或者拉取失败的通用解法镜像拉取慢在部分网络环境下非常常见。通用的解法是配置镜像加速器也就是 registry mirror。Windows 的 Docker Desktop 在 Settings - Docker Engine 里修改 JSON 配置macOS 相同。在配置里加入{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com, https://mirror.baidubce.com ] }不同服务商的加速地址有效性会变这里列的是曾经比较常用的公共加速地址。如果你用的是腾讯云、阿里云这类云厂商可以在控制台里找到专属加速地址稳定性更好把地址替换进去就行。配置完成后保存并重启 Docker Desktop 生效。如果配置加速器后还是拉取失败先手动清理残留的失败镜像层再重新拉取docker system prune docker pull ccr.ccs.tencentcloud.com/tencentcodebuddy/workbuddy:latest另外注意一点拉取失败时不要反复重试同一个命令先看错误信息。常见错误有两种超时和 manifest 不存在。超时先检查加速器配置manifest 不存在则大概率是镜像名或 tag 写错了可以按 CtrlC 先取消去官方文档核对一下镜像地址再拉。5.5 账号登录与 Token 关联问题容器跑起来了页面也能打开结果登录这步出问题这是另一种容易让人抓狂的情况。最常见的原因是系统时间和实际时间不一致。容器服务在跟认证服务器通信时会校验证书系统时间偏了会导致证书校验失败表现就是登录页一直转圈或者报网络错误。Windows 和 macOS 都出现过这个问题先把系统自动时间同步打开再刷新页面。还有情况是浏览器缓存了旧页面导致登录流程走到一半跳不回工作台。换一个无痕窗口或者换浏览器试一次能排除掉大部分前端缓存问题。如果换了浏览器还是不行就回容器那边看日志docker logs --tail 200 workbuddy日志里一般会写清楚是认证失败、网络不通还是服务内部错误按日志提示对症处理。企业用户如果遇到 SSO 登录不上去不要盲目重试先确认管理员这边的组织权限配置是否正确再做一次单点登录授权。个人用户则检查账号是否完成了邮箱验证和实名认证部分服务的登录环节会卡在未验证账号这一步上。收个尾两个平台装下来我的最直观感受是Windows 的坑集中在 WSL2 环境macOS 的坑集中在架构和权限但只要把 Docker 环境理顺WorkBuddy 本身的安装反而是最顺畅的一环。最后再分享一个小技巧安装完并确认能正常使用后先别急着关终端在挂载出的数据目录里建一个 README 文件记录你最终使用的镜像地址、端口、映射目录、登录账号。这些信息下次升级或换电脑重装时会救你的命毕竟大部分人不会把 docker run 命令记在脑子里而官方文档又可能改版。祝顺利跑通有问题对照第 5 章自查就行。