Neo Chat部署教程：本地 pnpm 开发、Docker 运行与 WebDAV/S3 同步配置

Neo Chat 是什么：部署前先对齐一句话

Neo Chat 是一个本地优先（local-first）的开源 AI 聊天工作台：多模型聊天、Agent 多步工具工作流、Deep Research 深度研究合在一个可自托管的 Web 界面里，MIT 协议，GitHub 约 1800 star（2026-09 查询为 1816），对话和文件默认存在浏览器本地。部署有四条路径：本地开发、Docker 快速体验、Compose 生产化、Vercel 或 Cloudflare Workers 托管；本文命令与变量名出自官方 README 和 docs/（2026-09-13 核实），工程解读单独标注。产品全景见Neo Chat 是什么，Agent 与 Deep Research 用法见专文，这里直接进部署。

本地开发部署：Node.js 24 与 pnpm 10.30.3

官方要求 Node.js 24 和 pnpm 10.30.3，版本经 Corepack 锁定，四条命令起服务，不需要全局装 pnpm。README Quick start 原样如下：

git clone https://github.com/u14app/neo-chat.git
cd neo-chat
corepack pnpm install --frozen-lockfile
corepack pnpm dev

打开 localhost:3000，在 Settings 添加供应商和 API Key 即可对话。corepack pnpm 按仓库锁定版本调用，绕开本机 pnpm 版本不一致的坑；常用命令还有 lint / typecheck / test / build（README）。

要配部署级默认值（比如默认供应商、搜索服务），把 .env.example 复制为 .env.local 再改，逐项含义查 docs/environment-variables.md。一个 Next.js 通识约束：NEXT_PUBLIC_* 是构建期变量，改完必须重新 build 才生效。

Docker 快速体验：一条命令

不打算拉源码，官方镜像一条命令就能在本机跑起来，端口绑定在回环地址上。README 原样命令：

docker run --rm -p 127.0.0.1:3000:3000 \
  -e ACCESS_PASSWORD='replace-with-a-strong-password' \
  -e BYOK_ALLOW_EPHEMERAL_KEY=true \
  ghcr.io/u14app/neo-chat:latest

打开 localhost:3000 输入访问密码即可。两个环境变量是理解部署的钥匙：

• ACCESS_PASSWORD：部署级密码闸门，非空即启用；支持逗号分隔多个密码，修改列表会使已有会话失效（docs/environment-variables.md）。没有用户隔离。
• BYOK_ALLOW_EPHEMERAL_KEY=true：允许用临时 BYOK 加密密钥。BYOK 即 Bring Your Own Key——浏览器里保存的 API Key 用服务器公钥加密成信封存放，服务器只在转发请求时解密。

README 在命令后紧跟着生产警告：此示例使用临时凭据加密密钥，生产前要配稳定的 BYOK 密钥，避免跨重启、跨副本的密钥轮换问题。部署文档补充了后果：重启后浏览器会刷新服务器公钥并重加密本地已存凭据一次；多副本各持一把临时密钥，对不上（docs/deployment-hardening.md）。体验可以，长期跑不行。

生产部署：稳定 BYOK 密钥与 Compose

长期运行的实例必须配齐三件套——稳定私钥 BYOK_PRIVATE_KEY_PEM、密钥 ID BYOK_KEY_ID、关闭临时密钥开关 BYOK_ALLOW_EPHEMERAL_KEY=false，缺一个都会在重启后出问题。密钥生成两条路：有源码跑 corepack pnpm byok:generate；没源码就把官方 scripts/generate-byok-key.mjs 用 Node 跑，三个输出拷进 .env（docs/deployment-hardening.md）。

Compose 两件套，官方文档原样精简：

compose.yaml：

services:
  neo-chat:
    image: ghcr.io/u14app/neo-chat:latest
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    restart: unless-stopped

.env（替换密码、私钥、密钥 ID 后再启动）：

DEPLOYMENT_MODE=local
ACCESS_PASSWORD=replace-with-a-strong-password
BYOK_ALLOW_EPHEMERAL_KEY=false
BYOK_PRIVATE_KEY_PEM='-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----'
BYOK_KEY_ID=replace-with-your-key-id
RATE_LIMIT_STORE=memory

chmod 600 .env
docker compose pull
docker compose up -d

生产环境关键变量速查：

变量	作用	注意点（docs/environment-variables.md）
ACCESS_PASSWORD	访问密码闸门	逗号是分隔符，密码内不能带逗号；生产 local 模式无密码会拒绝 API 请求
BYOK_PRIVATE_KEY_PEM	稳定私钥，解密 BYOK 信封	长期部署建议必配，多副本必须一致
BYOK_KEY_ID	当前密钥标识	换密钥时同步更换
BYOK_ALLOW_EPHEMERAL_KEY	是否允许临时密钥	生产设 false
DEPLOYMENT_MODE	local / hosted 安全策略	公网部署用 hosted
RATE_LIMIT_STORE 等三个 store	限流、解析任务、插件注册的存储	多实例用 upstash，单进程 memory 够用

镜像策略三点：latest 跟踪默认分支、并非稳定通道，生产固定 Git tag 或 sha256 摘要；官方镜像只构建 linux/amd64，ARM 主机需要模拟或源码构建；要公网访问就把 HTTPS 反向代理架在前面，容器端口保持绑定回环。改完配置用 Settings → deployment health 或 /api/health 验证就绪，带密码时可能先返回 401，属正常（docs/deployment-hardening.md）。

数据备份与同步：浏览器存储的边界

容器卷不备份对话——数据在浏览器里，备份和同步都要走应用内两条官方路径：ZIP 备份恢复、WebDAV/S3 端到端加密同步。部署文档原话：对话和上传文件默认是浏览器本地的，容器卷不做备份；迁移时保持浏览器 origin（协议、域名、端口）一致（docs/deployment-hardening.md）。

加密同步在 Settings → Sync 配置：选 WebDAV 或 S3/MinIO 后端，测试连接，创建加密 vault，随即保存恢复码和二维码。恢复码内含 256 位 vault 密钥，是另一台设备解密 vault 的唯一凭据，官方明确无法找回（docs/encrypted-sync.md）。

“端到端”在这里是字面意义：浏览器在上传前对每个文档和文件单独加密，AES-256-GCM 密钥从恢复码派生，远端对象名经 HMAC 派生、连本地路径都不暴露——你的 WebDAV 或 S3 服务商只能见到密文字节，服务端读不到任何内容。同步范围同样有明文清单：聊天元数据与消息树、设置、工作区、知识库元数据与文件、记忆、已装 Skill 数据会同步；凭据和 Research 扩展数据不进同步，后者靠 ZIP 备份转移（官方指定路径）。

四条部署路径怎么选

本机体验用 Docker 一条命令，长期自托管用 Compose 加稳定密钥，开发改码用 pnpm dev，免运维选无服务器托管。

路径	适用场景	前置与要点
corepack pnpm dev	二次开发、跟踪最新代码	Node.js 24 + pnpm 10.30.3；localhost:3000
docker run 快速体验	十分钟内先跑起来看看	临时 BYOK 密钥，重启轮换，仅体验
Docker Compose 生产	长期自托管、小团队共用	稳定 BYOK 三件套、强密码、HTTPS 反代
Vercel / Cloudflare Workers	无服务器、免运维	hosted 模式 + Upstash 共享存储；Workers 不支持本地 MCP bridge

无服务器路径补充两个事实：Vercel 用 Next.js 预设导入仓库即可；Cloudflare Workers 跑 corepack pnpm build:worker 和 corepack pnpm deploy:worker，部署脚本带 --keep-vars 保留面板变量（README）。Compose 的通用写法——restart 策略、env_file、反代网络——与本站SubBoost 的 Docker 部署教程是同一套思路，可互为参照。

上线前安全清单（工程建议，非官方强制）

以下七条组合官方要求与通用自托管实践，逐条过一遍再对外：

1. ACCESS_PASSWORD 用强密码，避免逗号字符
2. 公网访问一律套 HTTPS 反向代理，容器端口只绑回环
3. BYOK_ALLOW_EPHEMERAL_KEY=false，配稳定密钥对并另存备份——换密钥会使浏览器已存凭据失效
4. BYOK 场景不要设置 DEFAULT_PROVIDER_API_KEY：官方明确 DEFAULT_* 凭据由该部署的所有用户共享
5. TRUST_PROXY_HEADERS 默认 false，除非你的代理会剥离客户端伪造的转发头
6. 只有确有多实例需求才上 Upstash 三个共享存储
7. 升级前先在应用内做 ZIP 备份并查 CHANGELOG——镜像回滚不会回滚浏览器数据迁移

常见问题

neo chat docker 怎么跑？

用官方镜像一条 docker run 命令即可跑起，无需源码，设好密码即可进入界面。命令如下（端口绑定回环，ACCESS_PASSWORD 换成强密码）：

docker run --rm -p 127.0.0.1:3000:3000 \
  -e ACCESS_PASSWORD='replace-with-a-strong-password' \
  -e BYOK_ALLOW_EPHEMERAL_KEY=true \
  ghcr.io/u14app/neo-chat:latest

打开 localhost:3000 输入访问密码即用。该命令用临时密钥仅适合体验；长期运行用 Compose 配稳定 BYOK 三件套并套 HTTPS 反代。

本地部署 AI chat 需要自备 API Key 吗？

需要自备 API Key：Neo Chat 不内置模型，各家供应商的 Key 都由用户在 Settings 里自行填写。部署方也可用 DEFAULT_PROVIDER_* 配默认供应商，但官方明确这类凭据由所有用户共享；个人自托管保持 BYOK 更干净，密钥加密存于浏览器。

Neo Chat 的数据存在哪，换电脑怎么迁移？

默认存在浏览器本地存储，容器卷不备份对话；迁移用应用内 ZIP 备份恢复，或配 WebDAV/S3 端到端加密同步。同步前保存好 256 位恢复码，它是唯一解密凭据；迁移时保持浏览器 origin（协议、域名、端口）一致，否则数据会因来源不同而”看似丢失”。