解决什么问题
Cherry Studio 的官方发行版以桌面客户端为主（Windows / macOS / Linux），配置和数据都存在本机。但有几类场景天然需要”网页版”：
- 一台 NAS 或轻量服务器变成全家、全设备的 AI 入口——电视、平板、公司电脑打开浏览器就能用，不必每台机器装一遍客户端；
- API Key 不想散落到每一台设备上，集中放在一台机器里管理，换设备、丢手机都不用重新铺 Key；
- 团队内网共用一套入口，供应商配置、会话记录集中保管，而不是散落在各人工位电脑上。
Cherry Studio 是开源项目，社区提供了 Web 版自托管形态：把服务跑在自己的 Docker 里，用浏览器访问。本文给出一套从零到可用的部署流程。镜像地址、端口约定、环境变量等细节以官方仓库 README 为准【待补：官方仓库与镜像地址】，文中命令是通用的 Docker 自托管套路——拿到官方给出的镜像名和端口后可以直接套用。
环境与版本
- 一台 Linux 服务器或常开的主机：建议 2 核 4 GB 起步。Web 版本体只做”界面 + 请求转发”，不做模型推理，资源压力很小；真正吃资源的是模型端（云端 API 或独立部署的 Ollama），那部分不在本机跑。
- Docker Engine 与 Compose v2 插件：
docker compose version能输出正常版本号即可，不需要更复杂的环境。 - 一个模型供应商的 API Key：DeepSeek、硅基流动等 OpenAI 兼容平台均可，怎么配见文末相关阅读。
- 可选：一个域名 + 80/443 端口（公网访问与自动 HTTPS 用，纯内网使用可跳过）。
分步骤
第一步：安装 Docker（已有可跳过）
官方一键脚本，Debian/Ubuntu/CentOS 系通用：
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker
docker compose version # 确认 Compose v2 可用第二步：用 Compose 拉起服务
新建目录并写 docker-compose.yml：
services:
cherry-web:
image: 【待补：官方镜像地址，以官方 README 为准】
container_name: cherry-web
restart: unless-stopped
ports:
- "8080:【待补：容器内端口，以官方文档为准】"
volumes:
- ./data:【待补：容器内数据目录路径，配置与会话数据的落盘位置】
environment:
- TZ=Asia/Shanghaidocker compose up -d 拉起，docker logs -f cherry-web 盯日志直到出现监听端口的信息。首次初始化按页面引导走【待补：初始化流程截图与步骤说明】。两个写法提醒：restart: unless-stopped 让服务器重启后服务自动回来；volumes 那行是本文最重要的一行，原因见坑 1。
第三步：配置模型供应商
浏览器打开 http://服务器IP:8080 进设置，添加供应商、粘贴 API Key——这一步和桌面端完全同构，逐项操作参考 Cherry Studio 配置多个 AI 供应商教程。建议先只配一家验证链路，跑通后再补其他家，出问题时方便二分定位。
第四步：反代与 HTTPS（公网访问必做）
Caddy 两行配置搞定证书签发与续期：
ai.example.com {
reverse_proxy 127.0.0.1:8080
}Caddy 默认不对 SSE 流式响应做缓冲，对话的逐字输出不会被卡成”憋半天一口气吐完”。如果反代用 nginx，需要手动加 proxy_buffering off;——SSE 场景的标准处理，否则流式输出会被 nginx 攒着。
第五步：验证
curl -I http://127.0.0.1:8080 # 本机可达，返回 2xx/3xx
curl -I https://ai.example.com # 反代可达，证书生效浏览器发起一次真实对话，重点确认三件事：逐字流式输出正常；刷新页面后历史会话还在（说明数据卷挂载生效）；换一台设备登录同一入口，看到同一份供应商配置。
第六步：升级与备份
docker compose pull && docker compose up -d # 升级到最新镜像
tar czf cherry-backup-$(date +%F).tar.gz ./data # 数据目录冷备升级只替换镜像层，宿主机 ./data 不受影响——这正是第二步坚持挂卷的回报。备份建议放进 cron 每日一跑；恢复时解压回原路径再 up -d 即可。
常见坑
坑 1：没挂载数据卷，重建容器配置全丢
第一次跑通后随手 docker compose down && up，供应商配置和会话历史清零——镜像重建后容器层不保留数据。所有需要持久化的内容（数据库、上传文件、配置）必须通过 volumes 映射到宿主机目录，并把 ./data 纳入备份计划【待补：容器内具体数据目录路径】。
坑 2：API Key 明文写进 compose 文件还推到公开仓库
compose 文件常和笔记、脚本一起进 Git 仓库，Key 跟着泄露。正确做法：Key 放 .env 文件，compose 里用变量引用，.env 加进 .gitignore。已经泄露的 Key 不存侥幸，立刻去供应商后台作废重发。
坑 3：裸 HTTP 暴露公网
没有 HTTPS 的公网入口，API Key 和对话内容都是明文传输，链路上的任何节点都能嗅探。公网部署务必走 HTTPS（Caddy 自动签发，成本为零）；纯内网使用可以例外，但也别顺手把端口映射到路由器上——那等于把内网服务挂到了公网。
坑 4：流式输出被反代缓冲
症状：等待很久后回答整段一次性弹出，或者请求莫名超时。原因与处理见第四步：nginx 加 proxy_buffering off;，或换 Caddy。这个坑在所有自托管 AI 前端上都存在，属于通用网络层问题，与 Cherry Studio 本身无关。
最终效果
一台 2 核 4 GB 的机器即可稳定承载全家的 AI 问答入口：浏览器即开即用，Key 集中管理，会话与配置随数据卷持久化，公网访问带自动 HTTPS，升级一条命令完成。模型端想从云端 API 切到本地 Ollama，只需在供应商设置里把地址指向内网机器的 11434 端口，前端零改动【待补：实测容器内存占用与多设备并发表现】。