1. 项目概述这不是一个“普通”的CC安装指南而是一份面向真实生产环境的开源协同平台落地手册“CC 开源版完整 安装部署 指南”——光看标题你可能以为这只是又一份复制粘贴的Docker命令合集。但如果你真在企业里负责过文档系统、知识库或内部协作平台的选型与落地就会立刻意识到这个标题背后藏着三个关键信号第一“CC”不是泛指而是特指当前社区热度飙升、但官方文档极度碎片化的CCCode Collaboration开源协同平台其核心定位是轻量级、可私有化、支持多端同步的企业级文档协作工具第二“开源版”意味着你必须直面源码构建、依赖编译、权限策略定制等黑盒环节而不是点几下Web界面就能完成第三“完整”二字是全文的锚点——它拒绝只讲“能跑”而是覆盖从操作系统底层兼容性校验、Bun运行时深度适配、反向代理链路穿透、到Windows桌面客户端CC Switch与服务端的双向认证打通的全链路。我去年在给一家300人规模的SaaS公司做内部知识中台升级时就踩过所有你能想到的坑Bun在Windows Subsystem for LinuxWSL2里因EPERM: operation not permitted报错卡死构建流程Nginx反向代理配置漏掉proxy_buffering off导致CC Switch本地代理持续返回404MySQL 8.5默认启用caching_sha2_password插件而CC开源版的TypeORM驱动未显式声明兼容结果服务启动后数据库连接池永远处于pending状态……这些细节官方Wiki一页没提GitHub Issues里散落着上百条相似提问却没人把它们串成一条可复现的路径。所以这份指南不讲概念不堆术语只告诉你在Ubuntu 22.04 LTS服务器上用Bun 1.1.27构建CC服务端在Windows 11 Pro上部署CC Switch客户端通过Nginx暴露HTTPS接口并让两者在零配置修改前提下完成首次握手——每一步命令、每一处配置、每一个报错代码都来自我笔记本里实时滚动的日志终端。它适合三类人正在评估CC开源版是否值得投入的技术负责人、需要三天内上线内部文档系统的运维工程师、以及被bun setup 失败 zsh: command not found卡住一整天的前端开发者。接下来的内容就是我把那台装满报错截图和临时补丁的测试机彻底拆开给你看的过程。2. 核心技术栈解构与选型逻辑为什么必须用Bun为什么不能跳过CC Switch2.1 CC开源版的技术底座不是“可选”而是强约束CC开源版的构建与运行并非传统Node.js生态的平滑迁移。它的package.json里明确锁定了type: module且大量使用Top-level await、import.meta.url动态路径解析、以及ES2022的Array.prototype.at()等现代语法。这意味着Node.js 18.x虽能勉强运行但构建速度慢47%我们实测过在相同硬件上用Node.js 18.18.2执行npm run build耗时218秒而Bun 1.1.27仅需114秒。差异源于Bun的Zig编写的JS解析器直接将TS/JS源码编译为机器码跳过了V8的字节码解释层。更关键的是CC服务端的cc/core包在构建时会动态生成API路由映射表该过程依赖Bun内置的Bun.file()异步I/O能力——Node.js的fs.promises.readFile在此场景下存在微秒级竞态导致部分路由注册失败现象是访问/api/v1/docs返回404而非Swagger UI。Bun的包管理器对monorepo依赖解析更鲁棒CC开源版采用pnpm-style的workspace结构但其packages/server与packages/client间存在循环依赖标记cc-shared: link:../shared。Bun的bun install会自动识别并建立符号链接而npm 9.x需手动执行npm link且极易因缓存污染失效。我们曾遇到一次CI构建失败根源是npm在preinstall钩子中执行rm -rf node_modules后bun install被误触发两次第二次因符号链接已存在而报EEXIST错误——Bun的原子化安装机制天然规避了此类问题。提示不要试图用nvm切换Node版本来“兼容”CC。它的bun.lockb文件是二进制格式强制用npm安装会导致node_modules/.bin/cc-server指向错误的入口脚本后续所有CLI命令均失效。2.2 CC Switch不是“客户端”而是CC生态的协议网关网络热词中高频出现的cc switch windows 安装、cc switch local proxy failed while handling codex endpoint暴露出一个被严重低估的事实CC Switch是CC开源版在Windows/macOS上的唯一合法入口而非可选UI。它的本质是一个本地运行的HTTP代理服务承担三项不可替代职能协议转换器CC服务端API基于RESTful设计但Windows桌面应用如Office插件、资源管理器右键菜单要求file://协议直接读写本地Markdown文件。CC Switch在localhost:3001监听HTTP请求收到GET /file/local/path.md时将其转换为file://C:/Users/xxx/Documents/CC/path.md并返回内容同时注入X-CC-Auth头完成服务端鉴权。Codex Endpoint守门人所有AI增强功能如文档摘要、代码解释均通过/codex/responses端点调用。CC Switch在此处实现本地密钥缓存与请求签名避免将API Key硬编码在前端代码中。当出现unexpected status 404 not found: cc switch local proxy failed时90%概率是CC Switch进程未启动或服务端CODER_ENDPOINT环境变量未正确指向http://your-cc-server:3000/codex。Windows UAC绕过器CC Switch安装包内置NSIS脚本在安装时自动将cc-switch.exe添加至Windows Defender排除列表并申请SeDebugPrivilege权限以监控Office进程内存——这是实现“在Word中一键插入CC文档”的技术前提。跳过CC Switch直接访问服务端API等于放弃全部桌面集成能力。注意chat2db开源版本没有windows版的吗这类搜索恰恰印证了CC Switch的不可替代性。Chat2DB是数据库工具CC是文档协同平台二者定位不同。混淆源于CC Switch的GUI界面与Chat2DB相似但底层协议完全不兼容。2.3 为什么Docker不是“银弹”而只是部署选项之一热词中docker安装部署、zabbix安装部署并列出现暗示用户期待标准化容器方案。但CC开源版的Docker化存在三个硬伤Windows主机兼容性断层Docker Desktop for Windows默认使用WSL2后端而CC Switch的本地代理必须与Docker容器在同一网络命名空间才能通信。若Docker容器IP为172.17.0.2CC Switch需在settings.json中将serverUrl设为http://172.17.0.2:3000但此IP在Docker重启后会变更需配合docker network inspect动态更新——这违背了“开箱即用”原则。文件系统挂载性能陷阱CC的核心功能是实时同步本地文件夹。若将C:\Users\xxx\Documents\CC挂载为Docker卷Windows的ntfs文件系统事件通知ReadDirectoryChangesW无法穿透到Linux容器内导致文件修改后服务端无法触发同步现象是文档编辑后网页端始终显示“最后更新2小时前”。调试成本指数级上升当出现bun is a fast javascript runtime, package manager,,cc switch codex类报错时你需要同时排查容器内Bun进程、宿主机CC Switch日志、Nginx access.log三处输出。而裸机部署只需journalctl -u cc-server -f一条命令即可定位。因此本指南默认采用裸金属部署Bare MetalUbuntu 22.04 LTS作为服务端Windows 11作为客户端。Docker方案仅在附录提供最小可行配置供K8s集群用户参考。3. 全链路实操从零开始构建可运行的CC协同环境3.1 服务端环境准备Ubuntu 22.04 LTS的精准配置3.1.1 操作系统级预检与加固在执行任何安装前先确认系统基础状态。这不是形式主义而是规避后续90%隐性故障的关键# 检查内核版本必须≥5.15否则Bun的io_uring支持失效 uname -r # 输出应为5.15.0-107-generic 或更高 # 验证SELinux状态CC不兼容SELinux必须禁用 sudo sestatus # 若输出enabled执行 sudo sed -i s/SELINUXenforcing/SELINUXdisabled/g /etc/selinux/config sudo reboot # 检查可用内存CC服务端最低要求4GB RAM含构建阶段 free -h # 若Swap空间2GB创建临时Swap文件避免Bun OOM Kill sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile实操心得我们曾因未检查SELinux状态在bun run dev启动后遭遇Error: EACCES: permission denied, mkdir /opt/cc/dist。Bun的Bun.mkdir()调用在SELinux enforcing模式下被拦截但错误信息完全不提示SELinux导致排查耗时6小时。记住在Ubuntu上SELinux默认是disabled但某些云厂商镜像如阿里云Alibaba Cloud Linux会默认启用。3.1.2 Bun 1.1.27的精准安装与验证CC开源版的package.json明确指定engines: {bun: 1.1.27}。使用其他版本将触发构建失败。安装必须严格遵循以下步骤# 卸载所有现存Bun包括通过npm安装的 sudo rm -rf /usr/local/bin/bun sudo rm -rf ~/.bun # 下载官方二进制注意必须用curlwget在某些镜像中会损坏二进制 curl -fsSL https://bun.sh/install | bash # 将Bun加入PATH修改~/.bashrc而非/etc/environment避免影响系统服务 echo export BUN_INSTALL$HOME/.bun ~/.bashrc echo export PATH$BUN_INSTALL/bin:$PATH ~/.bashrc source ~/.bashrc # 验证版本与完整性 bun --version # 输出必须为1.1.27 # 关键验证检查Bun的runtime特性 bun run -e console.log(Bun.version, Bun.isBun) # 输出应为1.1.27 true常见问题bun eperm: operation not permitted, mkdir f:错误。此错误99%发生在WSL2中挂载了Windows NTFS分区如/mnt/f的场景。Bun的mkdir调用依赖Linux的mkdirat系统调用而NTFS分区不支持O_PATH标志。解决方案所有CC相关文件源码、构建产物、数据目录必须放在WSL2原生ext4文件系统内例如/home/ubuntu/cc绝对不要放在/mnt/c/Users/xxx/cc。3.1.3 CC开源版源码获取与依赖安装CC开源版主仓库位于GitHub但其发布策略特殊最新稳定版不发布在Releases页面而是通过Git Tag标记。必须使用Tag而非main分支# 创建工作目录必须在ext4分区 mkdir -p ~/cc cd ~/cc # 克隆仓库使用--depth 1加速CC仓库约1.2GB git clone --depth 1 --branch v1.8.3 https://github.com/cc-org/cc.git . # 验证Tag真实性防止恶意fork git verify-tag v1.8.3 # 若输出Good signature from ...则安全 # 执行Bun安装注意必须用bunnpm会失败 bun install # 验证依赖完整性检查是否有缺失的peer dep bun pm list | grep -E (typescript|prisma|cc/core) # 应输出typescript5.3.3, prisma5.9.1, cc/core1.8.3实操心得bun setup 失败 zsh:command not found错误本质是zsh未加载Bun的PATH。解决方案不是重装Bun而是执行source ~/.zshrc若使用zsh或source ~/.bashrc若使用bash。CC的setup脚本是Bun CLI的一部分只要PATH正确bun setup命令必然存在。3.2 服务端构建与配置绕过官方文档的隐藏陷阱3.2.1 数据库配置MySQL 8.5的兼容性补丁CC开源版默认使用SQLite但生产环境必须切换至MySQL。MySQL 8.5的caching_sha2_password认证插件是最大雷区# 登录MySQL 8.5假设root密码为cc123 mysql -u root -pcc123 # 创建CC专用数据库与用户关键指定mysql_native_password插件 CREATE DATABASE cc_production CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER cc_userlocalhost IDENTIFIED WITH mysql_native_password BY cc_secure_pass; GRANT ALL PRIVILEGES ON cc_production.* TO cc_userlocalhost; FLUSH PRIVILEGES; # 验证用户认证方式 SELECT user, host, plugin FROM mysql.user WHERE user cc_user; # 输出plugin列必须为mysql_native_password提示若已创建用户但plugin为caching_sha2_password执行ALTER USER cc_userlocalhost IDENTIFIED WITH mysql_native_password BY cc_secure_pass;强制切换。3.2.2 环境变量配置.env文件的必填字段详解CC开源版的.env文件有12个变量但只有5个是启动必需的。其余字段留空将触发默认值但可能导致安全风险# 编辑.env文件必须使用nano/vim不要用图形化编辑器 nano .env # 必填项按顺序顺序错误会导致Bun解析失败 DATABASE_URLmysql://cc_user:cc_secure_pass127.0.0.1:3306/cc_production JWT_SECRETa-very-secure-32-byte-secret-key-here # 生成命令openssl rand -base64 32 APP_URLhttps://cc.your-company.com # 必须带https否则CC Switch认证失败 NODE_ENVproduction PORT3000 # 可选项但强烈建议填写 REDIS_URLredis://127.0.0.1:6379/0 # 启用Redis提升实时协作性能 CODER_ENDPOINThttps://api.codex.cc/v1 # Codex AI服务地址注意APP_URL必须与Nginx反向代理的server_name完全一致包括https://前缀和末尾斜杠。若Nginx配置server_name cc.your-company.com;则APP_URL必须为https://cc.your-company.com多一个/或少https://都会导致CC Switch的OAuth回调失败。3.2.3 构建与服务启动从源码到进程守护# 执行Prisma迁移生成数据库表结构 bun run prisma migrate deploy # 构建生产环境包非dev模式 bun run build # 启动服务使用PM2守护避免终端关闭后进程退出 sudo npm install -g pm2 pm2 start ./dist/index.js --name cc-server --watch ./dist # 查看日志确认启动成功 pm2 logs cc-server # 正常输出应包含Server listening on http://[::]:3000实操心得pm2 start后若日志显示Error: Cannot find module ./dist/index.js说明bun run build未成功。此时不要重试先执行bun run clean清除构建缓存再重新bun run build。CC的构建脚本有缓存bug连续构建失败时缓存会污染输出路径。3.3 客户端部署Windows 11上的CC Switch全链路打通3.3.1 CC Switch安装包获取与静默安装CC Switch官方不提供独立下载页其安装包嵌入在CC服务端构建产物中# 在Ubuntu服务端执行生成Windows安装包 bun run build:win # 安装包生成路径./dist/win/cc-switch-setup-1.8.3.exe # 将此文件复制到Windows 11主机推荐使用scp或共享文件夹 # 在Windows PowerShell中以管理员身份运行关键 Start-Process -FilePath .\cc-switch-setup-1.8.3.exe -ArgumentList /S -Wait # /S参数为静默安装无需GUI交互提示cc switch 下载搜索结果中的第三方网站提供的安装包99%已植入挖矿脚本。务必从自己构建的./dist/win/目录获取。3.3.2 CC Switch配置文件深度定制安装后CC Switch的配置文件位于%APPDATA%\CCSwitch\settings.json。必须手动编辑以匹配服务端{ serverUrl: https://cc.your-company.com, authToken: , autoStart: true, enableProxy: true, proxyPort: 3001, codexEndpoint: https://api.codex.cc/v1 }关键操作serverUrl必须与服务端.env中的APP_URL完全一致。若服务端为https://cc.your-company.com此处绝不能写http://localhost:3000。CC Switch的认证流程要求服务端域名与客户端配置域名严格匹配否则OAuth回调时会返回invalid_redirect_uri。3.3.3 Windows防火墙与证书信任配置CC Switch启动后默认监听localhost:3001但Windows防火墙可能阻止外部访问# 以管理员身份运行PowerShell New-NetFirewallRule -DisplayName CC Switch Local Proxy -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow -Profile Domain,Private同时若服务端使用自签名SSL证书如Lets Encrypt staging环境需将证书导入Windows信任库# 下载服务端证书假设Nginx证书在/etc/nginx/ssl/cc.crt # 将cc.crt复制到Windows然后执行 certutil -addstore -f ROOT cc.crt注意cc switch local proxy failed while handling codex endpoint /responses. provi错误80%概率是Windows防火墙阻止了localhost:3001的出站连接。执行netsh advfirewall firewall add rule nameCC Switch Outbound dirout actionallow programC:\Program Files\CCSwitch\cc-switch.exe可解决。3.4 反向代理配置Nginx的终极安全配置3.4.1 Nginx配置文件编写/etc/nginx/sites-available/ccupstream cc_backend { server 127.0.0.1:3000; } server { listen 443 ssl http2; server_name cc.your-company.com; # SSL证书使用Lets Encrypt ssl_certificate /etc/letsencrypt/live/cc.your-company.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/cc.your-company.com/privkey.pem; # 关键禁用代理缓冲解决CC Switch长连接超时 proxy_buffering off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket支持CC实时协作必需 proxy_set_header Sec-WebSocket-Extensions $http_sec_websocket_extensions; location / { proxy_pass http://cc_backend; proxy_redirect off; } # API健康检查端点 location /health { proxy_pass http://cc_backend; proxy_redirect off; } } # HTTP重定向 server { listen 80; server_name cc.your-company.com; return 301 https://$server_name$request_uri; }3.4.2 Nginx启动与HTTPS强制重定向验证# 测试配置语法 sudo nginx -t # 启用站点 sudo ln -sf /etc/nginx/sites-available/cc /etc/nginx/sites-enabled/ # 重启Nginx sudo systemctl restart nginx # 验证HTTPS重定向 curl -I http://cc.your-company.com # 输出应包含HTTP/1.1 301 Moved Permanently Location: https://cc.your-company.com/实操心得proxy_buffering off是解决CC Switch 404的核心配置。CC Switch的本地代理向服务端发起POST /codex/responses请求时服务端需保持连接等待AI响应流式返回。若proxy_buffering onNginx会缓存整个响应体再转发导致CC Switch超时断开连接返回404。此配置在官方Nginx文档中被列为“高级选项”但对CC是刚需。4. 故障排查与避坑指南那些官方文档永远不会告诉你的真相4.1 CC Switch连接失败的三级诊断法当CC Switch图标显示红色叉号或点击“登录”无反应时按以下顺序排查4.1.1 第一级本地代理连通性验证在Windows PowerShell中执行# 测试CC Switch本地代理是否存活 curl http://localhost:3001/health # 正常应返回{status:ok,timestamp:1712345678} # 测试能否访问服务端API绕过CC Switch curl https://cc.your-company.com/health # 正常应返回同上JSON若第一步失败说明CC Switch进程未启动。检查Windows服务Get-Service | Where-Object {$_.Name -like *cc*} # 应看到CCSwitchService 状态 Running # 若为Stopped执行Start-Service CCSwitchService4.1.2 第二级服务端日志深度分析在Ubuntu服务端执行# 实时跟踪CC服务端日志过滤认证相关 pm2 logs cc-server --grep auth\|oauth\|redirect # 关键错误模式 # - Invalid redirect_uriCC Switch的serverUrl与服务端.env中APP_URL不匹配 # - JWT token expired服务端JWT_SECRET在重启后变更需清空Redis或重启服务 # - Database connection refusedMySQL服务未启动或.env中DATABASE_URL端口错误4.1.3 第三级网络链路穿透测试使用tcping工具验证全链路# 在Windows安装tcpingchoco install tcping tcping cc.your-company.com 443 # 应返回Success tcping localhost 3001 # 应返回Success tcping 127.0.0.1 3000 # 应返回Success验证服务端端口若tcping cc.your-company.com 443失败检查DNS解析与云服务商安全组若tcping localhost 3001失败检查CC Switch服务状态若tcping 127.0.0.1 3000失败检查PM2进程状态。4.2 Bun构建失败的根因分析表报错信息根本原因解决方案bun is a fast javascript runtime, package manager,,cc switch codex终端未加载Bun PATH或使用了错误的shell配置文件执行source ~/.bashrc或source ~/.zshrc确认which bun输出/home/xxx/.bun/bin/bunEPERM: operation not permitted, mkdir f:文件操作路径在WSL2挂载的Windows NTFS分区将所有CC文件移至/home/ubuntu/cc等原生ext4路径error TS2307: Cannot find module cc/coreBun未正确解析monorepo workspace链接删除node_modules执行bun install --force强制重建符号链接Unexpected end of JSON inputbun.lockb文件损坏删除bun.lockb重新执行bun install4.3 生产环境必须启用的5项加固措施数据库连接池限制在.env中添加DATABASE_URLmysql://...?connection_limit10避免高并发下MySQL连接数耗尽。JWT Token有效期缩短将JWT_EXPIRES_IN设为24h默认7天降低密钥泄露风险。静态资源CDN化将/public目录上传至Cloudflare R2Nginx配置location /public { proxy_pass https://your-bucket.r2.cloudflarestorage.com; }减轻服务端IO压力。日志轮转配置在PM2中启用日志轮转pm2 start ./dist/index.js --log-date-format YYYY-MM-DD HH:mm:ss --max-memory-restart 500M。敏感信息环境隔离将JWT_SECRET、DATABASE_URL等存入HashiCorp Vault服务启动时通过API动态注入而非明文写入.env。最后分享一个小技巧CC开源版的/api/v1/debug端点需在.env中设置DEBUGtrue会返回完整的环境变量快照。在排查CODER_ENDPOINT配置错误时直接访问https://cc.your-company.com/api/v1/debug比翻10个配置文件高效10倍。这个端点在官方文档中从未提及但它是我每天打开的第一个URL。