云服务器部署

在线一条命令安装，或本机打包离线镜像；由 Nginx 提供 HTTPS 反代。

生产只运行应用容器，连接宿主机已有的 PostgreSQL（必须）和 Redis（可选）；文件使用云对象存储，联网搜索使用云 API。HTTPS 由宿主机 Nginx 或 Caddy 提供。通用 Compose 说明见 Docker 自托管。

默认资源档案为 profiles/2g.env（应用内存上限 512m）。安装前请先启动 PostgreSQL 容器；Redis 与对象存储按需配置。

方式一：在线安装（推荐）

目标主机可访问 GHCR（或你指定的镜像仓库）时，无需本机打包：

curl -fsSL https://raw.githubusercontent.com/Hyk260/PureChatNext/main/docker-compose/deploy/install-online.sh \
  | sudo APP_URL=https://chat.example.com bash

脚本会把编排文件下载到 /opt/purechat（可用 PURECHAT_HOME 覆盖），拉取 ghcr.io/hyk260/purechat-next，生成 .env 并启动。

常用变量：

变量	说明
`APP_URL`	正式 HTTPS 地址（CORS 默认允许该地址，不必再配 `ALLOWED_ORIGINS`）
`PURECHAT_HOME`	安装目录，默认 `/opt/purechat`
`PURECHAT_REF`	下载编排文件用的 Git 引用，默认 `main`；发版后可改为 `v0.2.5`
`PURECHAT_IMAGE`	应用镜像，默认 `ghcr.io/hyk260/purechat-next:latest`
`PURECHAT_VERSION`	未设 `PURECHAT_IMAGE` 时的 tag
`PURECHAT_REFRESH`	设为 `1` 时按 `PURECHAT_REF` 重新下载编排（保留 `.env`）

临时用公网 IP（安全组放行 3210）：

curl -fsSL https://raw.githubusercontent.com/Hyk260/PureChatNext/main/docker-compose/deploy/install-online.sh \
  | sudo bash -s --
# 若已下载到 /opt/purechat：
sudo /opt/purechat/start-ip.sh

镜像由 GitHub Actions 在推送 main 或 v* tag 时发布到 GHCR。首次发布后请在 GitHub Packages 将 purechat-next 设为 Public，否则匿名 docker pull 会失败。

升级（保留 .env）：

sudo PURECHAT_REFRESH=1 PURECHAT_REF=main \
  PURECHAT_IMAGE=ghcr.io/hyk260/purechat-next:latest \
  /opt/purechat/install-online.sh up

或只更新镜像、不重下编排：

cd /opt/purechat
sudo PURECHAT_IMAGE=ghcr.io/hyk260/purechat-next:latest ./install.sh --online up

方式二：离线包

本机无外网构建能力、或目标主机不能拉镜像时使用。

本机 pnpm docker:pack
  ↓ 首次 pnpm docker:upload -- --install --app-url https://chat.example.com
  ↓ 升级 pnpm docker:upload -- --up
反代 HTTPS → 127.0.0.1:3210

1. 本机打包

git clone https://github.com/Hyk260/PureChatNext.git
cd PureChatNext
pnpm install
pnpm docker:pack

默认导出 linux/amd64 离线包。Apple Silicon 上若本地镜像是 arm64，打包时会按 amd64 重新构建，并默认经镜像站拉取基础镜像（可用 DOCKER_HUB_MIRROR、GHCR_MIRROR 覆盖）。--no-cn-mirror 会跳过镜像站。离线包只含应用镜像，PostgreSQL 与 Redis 使用目标主机上已有的实例。完整参数（--platform、--output 等）见 Docker 自托管 · 命令参考。

--skip-build 只导出本机已有的 purechat-next:local，不会根据当前源码重建。刚打完包、只想再导出一次时才用：

pnpm docker:pack -- --skip-build

产物是 dist/docker-offline/purechat-next-offline.tar，内含：

purechat-next:local 应用镜像
生产 Compose、.env.example、2g 档案
install.sh、start-ip.sh

打包不会带上本机 docker-compose/deploy/.env。密钥在目标主机上生成。

2. 上传

不要把 SSH 私钥写进应用 .env 或 packages/env，那些是运行时配置。上传只用本机环境变量或 docker-compose/deploy/upload.env。

cp docker-compose/deploy/upload.env.example docker-compose/deploy/upload.env
chmod 600 docker-compose/deploy/upload.env
# 填写 PURECHAT_SSH_HOST，以及 PURECHAT_SSH_KEY_FILE 或 PURECHAT_SSH_KEY
pnpm docker:upload -- --install --app-url https://chat.example.com

也可不建文件，直接 export：

export PURECHAT_SSH_HOST=203.0.113.10
export PURECHAT_SSH_USER=root
export PURECHAT_SSH_KEY_FILE="$HOME/.ssh/id_ed25519"
# 或：export PURECHAT_SSH_KEY="$(cat ~/.ssh/id_ed25519)"
pnpm docker:upload -- --install --app-url https://chat.example.com

已安装过、只更新镜像时：

pnpm docker:upload -- --up

--install 会上传、解压到 /opt/purechat 并执行 install.sh。--up 同样上传并解压，再执行 install.sh up，不会覆盖已有 .env。只上传不解压用默认命令；--extract 只解压、不启动容器。

变量	必填	说明
`PURECHAT_SSH_HOST`	是	服务器 IP 或域名；也可 `root@203.0.113.10`
`PURECHAT_SSH_USER`	否	默认 `root`
`PURECHAT_SSH_PORT`	否	默认 `22`；改了就要在安全组放行同一端口
`PURECHAT_SSH_KEY_FILE`	三选一	私钥路径，推荐
`PURECHAT_SSH_KEY`	三选一	私钥全文；单行可用 `\n`。不要提交、不要打印
ssh-agent	三选一	未设上面两项时使用；带口令的密钥请先 `ssh-add`
`PURECHAT_REMOTE_TAR`	否	root 默认 `/opt/purechat-next-offline.tar`；非 root 默认 `/tmp/...`
`PURECHAT_HOME`	否	解压目录，默认 `/opt/purechat`（不要有空格）
`PURECHAT_SSH_EXTRA_OPTS`	否	额外 ssh 参数，例如 `-J bastion`

当前 shell 里已 export 的值优先于 upload.env。完整示例见 docker-compose/deploy/upload.env.example。也兼容旧文件名 .upload.env。

仍可手动 scp：

scp dist/docker-offline/purechat-next-offline.tar root@SERVER:/opt/purechat-next-offline.tar

建议解压到 /opt/purechat（路径不要有空格）。

上传所需的服务器权限

上传只走 SSH。云安全组和主机防火墙按下面放行即可。

端口	方向	谁访问	何时需要
SSH（默认 22，或你改过的 `PURECHAT_SSH_PORT`）	入站	仅你的出口 IP	上传、远程解压、远程 `install.sh`
80 / 443	入站	公网	正式 HTTPS 反代。上传本身不需要
3210	入站	公网	仅 `start-ip.sh` 临时调试；正式环境不要开
5432 / 6379	—	不要对公网开放	PostgreSQL / Redis 只给本机 Docker 网络

SSH 账号需要：

公钥登录（脚本使用 BatchMode，不支持交互输密码）
root：可直接写 /opt、调用 Docker（1Panel 常见）
非 root：对目标目录可写（tar 默认 /tmp），并且 sudo -n 免密，以便 --extract / --install / --up 解压到 /opt/purechat 和执行 install.sh
运行 install.sh 时能连接 Docker（用户在 docker 组，或使用 sudo）

建议：关闭密码登录，只放行你的 IP 访问 SSH，磁盘至少留出离线包两倍空间（约 300MB 量级，镜像解开后更大）。

首次配置 SSH 公钥

端口通了但仍 Permission denied (publickey,password)，说明 SSH 服务正常，只是 root 还没有你的公钥。脚本不会弹出密码框。

1Panel（推荐）

「基础配置」保持现状即可：连接端口 22、root 允许登录、密钥认证开启。密码认证可先留着，公钥通了再关。
点顶部 授权密钥（不要用「密钥信息」——那是服务器自己的主机密钥，不是登录公钥）。
本机执行 cat ~/.ssh/id_ed25519.pub，把整行（以 ssh-ed25519 开头）粘贴进去并保存。
本机 docker-compose/deploy/upload.env 写上 PURECHAT_SSH_KEY_FILE=~/.ssh/id_ed25519，再执行 pnpm docker:upload。

「反向解析」建议关掉，只影响连接速度，不是这次失败的原因。

命令行备用（1Panel 终端或云厂商 VNC，root）：

mkdir -p /root/.ssh
chmod 700 /root/.ssh
echo 'ssh-ed25519 AAAA... 你的公钥整行' >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys

没有本机公钥时先生成：ssh-keygen -t ed25519 -C "purechat-upload"。私钥若有口令，先 ssh-add ~/.ssh/id_ed25519。

3. 安装

确认已安装 Docker 与 Compose。域名 A 记录解析到主机公网 IP（若使用域名）。

sudo mkdir -p /opt/purechat
sudo tar -xf /opt/purechat-next-offline.tar -C /opt/purechat
# 有域名（把 APP_URL 换成你的 HTTPS 地址）：
sudo APP_URL=https://chat.example.com /opt/purechat/install.sh
# 临时用公网 IP 调试：
sudo /opt/purechat/start-ip.sh

start-ip.sh 会探测公网 IP、写入 APP_URL=http://IP:3210、把应用绑到 0.0.0.0（需在安全组放行 3210）。Cookie / OAuth / 微信渠道在 HTTP+IP 下可能异常；正式环境请改用域名，并把 APP_BIND_ADDRESS 改回 127.0.0.1。

安装脚本会：检测应用镜像 → 生成或复用 .env → 在已运行的 PostgreSQL 容器中创建用户和数据库 purechat（若存在 Redis 则可选接入）→ 将应用加入共享 Docker 网络 → docker compose up。已有 .env 时不覆盖密钥。安装前请先启动 PostgreSQL。

网页聊天可把模型 Provider 密钥写入 /opt/purechat/docker-compose/deploy/.env（例如 DEEPSEEK_API_KEY）作为兜底；微信 / QQ 必须在设置页保存用户自己的密钥。然后：

sudo /opt/purechat/install.sh up

不要单独导入 docker-compose.yml：工作目录必须是解压后的离线包根目录。离线模式不要在目标主机上 docker pull 或 docker build。

启动后应用默认只监听 127.0.0.1:3210。容器会获取 advisory lock 并执行 Drizzle 迁移；迁移失败则应用不会起来。

cd /opt/purechat
sudo ./install.sh ps
curl --fail http://127.0.0.1:3210/api/health

配置反代与证书

为正式域名创建反向代理，指到 http://127.0.0.1:3210。
开启 WebSocket。
申请 TLS 证书。
在站点 Nginx 中使用：

location / {
  proxy_pass http://127.0.0.1:3210;
  proxy_http_version 1.1;
  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;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
  proxy_buffering off;
  proxy_cache off;
  proxy_read_timeout 300s;
  proxy_send_timeout 300s;
}

proxy_buffering off 和 300s 超时是为了 AI 流式输出。

更新环境变量

只编辑 /opt/purechat/docker-compose/deploy/.env，不要在 1Panel 容器详情里改环境变量（下次 up 会被 .env 覆盖）。

环境变量在创建容器时注入。1Panel「重启」、docker restart、./install.sh restart 都不会加载新的 .env，必须重建容器：

cd /opt/purechat
sudo ./install.sh up --force-recreate

改完 APP_URL、对象存储、模型密钥、DISABLE_REDIS 等之后都用这一条。确认已进容器：

sudo ./install.sh exec app printenv APP_URL REDIS_URL DISABLE_REDIS

up 会重新探测 PostgreSQL / Redis，并可能改写 REDIS_URL、REDIS_USERNAME、REDIS_PASSWORD。

验收

浏览器打开你的 APP_URL（例如 https://chat.example.com），页面可加载。
https://chat.example.com/api/health（换成你的域名）返回健康 JSON；未配置的可选依赖为 skipped。
注册或登录后能发送一条短对话，流式输出完整结束。

升级与备份

升级前备份数据库（文件放到 Docker 卷之外，例如 /opt/backups）：

sudo mkdir -p /opt/backups
docker exec -T postgresql pg_dump -U purechat -d purechat --format=custom --no-owner \
  > /opt/backups/purechat-$(date +%F).dump

容器名以 .env 中的 POSTGRES_CONTAINER 为准，缺省多为 postgresql。

在线：见上文「升级」；会拉取新镜像并 up，不要覆盖 .env。

离线：本机拉代码后执行 pnpm docker:pack:upgrade（依次打包、上传并执行升级；不要使用 --skip-build）。上传会覆盖镜像档案和 install.sh，不会覆盖 docker-compose/deploy/.env。也可手动：

sudo tar -xf /opt/purechat-next-offline.tar -C /opt/purechat
sudo /opt/purechat/install.sh up

install.sh up 会在应用镜像档案变化时重新 docker load，并 --force-recreate app 容器。只 docker restart 不会切换到新镜像，也不会加载新的 .env：容器创建时钉死了镜像 ID 和环境变量。改镜像或改 .env 都用 sudo ./install.sh up --force-recreate。

离线包本身不含 .env。不要在生产环境执行 down -v 或 docker system prune --volumes。

注意事项

离线上传密钥：SSH 私钥只放本机 upload.env 或环境变量，不要写进服务器上的应用 .env。
渠道：微信 / QQ Gateway 已打进 app 容器，仍要公网 HTTPS。见微信渠道与 QQ 渠道。
邮件：验证邮箱和重置密码需要 SMTP，见邮件服务。
不要用公网 IP 当正式 APP_URL：Cookie、CORS、证书和后续换域名都会出问题。
数据库：使用专用用户和数据库 purechat，不要与其它应用共用同一套库。不要把 5432、6379 暴露到公网。
文件与搜索：配置 S3 兼容对象存储；SEARCH_PROVIDERS 可填 tavily 等，默认不启用自建搜索。
健康检查失败：应用日志停在 [Database] waiting for PostgreSQL 时，核对 POSTGRES_HOST（应为数据库容器名）和 POSTGRES_PASSWORD，并确认 PostgreSQL 已启动。
Redis WRONGPASS：应用日志刷 invalid username-password 时，先确认 Redis 容器环境变量 REDIS_PASSWORD 与 docker-compose/deploy/.env 一致，再执行 sudo ./install.sh up --force-recreate。脚本会校验 ACL / 实例密码；认证失败则清空 REDIS_URL，应用降级运行。不需要 Redis 时可在 .env 设 DISABLE_REDIS=1 后同样重建容器。

常用命令

cd /opt/purechat

sudo ./install.sh ps
sudo ./install.sh logs --tail=100 app
sudo ./install.sh up --force-recreate