如何在服务器上安装OriginSNS

2026-08-17官方教程

OriginSNS 安装部署说明

本文说明如何在服务器上安装与运维 OriginSNS。

同目录还有纯文本版：部署说明.txt（内容一致，方便在服务器终端直接 cat / less）。

默认部署目录： /www/wwwroot/origin 若你改了目录名，请把文中路径全部换成实际路径，并同步修改 .env 里的 ORIGIN_HOST_DEPLOY_DIR。

命令在哪执行（重要）

凡写「在部署目录执行」：先进入含 docker-compose.yml 的目录，再敲命令。
推荐用 SSH，或宝塔面板 → 终端（不要只靠编排面板点「重建」排错）。
多数示例都以这两行开头，复制时请一起执行：

```bash cd /www/wwwroot/origin

然后才是具体命令

```

未执行 ./ode install 时：即使在部署目录，也要写 ./ode …（前面的 ./ 不能省）。
已执行 sudo ./ode install 后：可在任意目录直接敲 ode …。

默认端口： 宿主机 9620 → 容器内 3000 对外只开 80 / 443（及 SSH 22）；不要把 9620、5432、6379 暴露到公网。建议关闭宝塔「系统防火墙」，入站安全用云厂商安全组即可（详见文末错误说明）。

本目录主要文件

| 文件 | 说明 | |------|------| | docker-compose.yml | 国内机默认 Compose | | docker-compose.us.yml | 美国/海外完整 Compose（需手动 -f） | | .env.example / .env.us.example | 环境变量模板 | | ode | 运维命令行 | | 宝塔编排路径.txt | 宝塔 Compose 路径说明（必读） | | nginx-hsts.example.conf | 反代层 HSTS 示例（可选） | | scripts/ | 部署与运维脚本 |

---

首次部署：步骤总览

1. [第一步：准备服务器与 Docker](#第一步准备服务器与-docker) 2. [第二步：上传并解压部署包](#第二步上传并解压部署包) 3. [第三步：配置 .env（必做）](#第三步配置-env必做) 4. [第四步：启动服务](#第四步启动服务) 5. [第五步：验收容器与健康检查](#第五步验收容器与健康检查) 6. [第六步：宝塔网站 + 反向代理 + HTTPS](#第六步宝塔网站--反向代理--https) 7. [第七步：注册管理员并进入后台](#第七步注册管理员并进入后台)

美国/海外机在第三、四步改用 US 模板（见 [美国 / 海外服务器](#美国--海外服务器us)）。装好后的升级、ode 运维、错误对照见文后章节。

---

第一步：准备服务器与 Docker

需要：

Linux + 宝塔
内存建议 2GB+，磁盘建议 20GB+
域名已解析到本机（国内站需备案）

安装 Docker： 宝塔 → 软件商店 → 搜索 Docker → 安装「Docker 管理器」→ 状态为运行中

在任意目录验证：

``bash docker --version docker compose version ``

两条都有版本号输出 → 进入第二步。

---

第二步：上传并解压部署包

1. 把收到的 origin-deploy-*.zip 上传到服务器，例如 /www/wwwroot/

2. 在终端执行（文件名换成你实际的 zip）：

``bash cd /www/wwwroot unzip origin-deploy-x.x.x.zip mv deploy-package origin cd origin ls ``

应能看到：docker-compose.yml、.env.example、ode、scripts/ 等。

若解压后没有 deploy-package 这一层（文件直接散落）：

```bash cd /www/wwwroot mkdir -p origin

把解压出的文件全部移进 origin 后：

cd origin ```

确认当前目录正确后 → 进入第三步。

---

第三步：配置 .env（必做）

``bash cd /www/wwwroot/origin ``

3.1 复制模板

国内机：

``bash cp .env.example .env ``

美国/海外机：

``bash cp .env.us.example .env ``

（第四步启动时必须带 -f docker-compose.us.yml，见 [美国 / 海外](#美国--海外服务器us)）

3.2 生成两个密钥（各执行一次，两次结果不要相同）

``bash openssl rand -base64 32 ``

终端会打印一长串，再执行一次同样命令，得到第二串。

编辑 .env（宝塔「文件」打开，或 nano .env），填入（不要带引号、不要首尾空格）：

``env SESSION_SECRET=第一次生成的那串 ORIGIN_LICENSE_ENCRYPTION_KEY=第二次生成的那串 ``

注意：

两个值必须不同
上线后不要随意改 SESSION_SECRET（已登录用户会全部掉线）
若提示没有 openssl：宝塔终端一般自带；或用系统包管理器安装 openssl

3.3 填写站点地址

``env NEXT_PUBLIC_APP_URL=https://你的域名 ``

必须带 https://，不要末尾斜杠（例：https://bbs.example.com）

3.4 数据库密码（新站强烈建议改掉默认值）

下面四项必须一致（用户名/库名若改也要四处对齐）：

``env POSTGRES_USER=postgres POSTGRES_PASSWORD=你的强密码 POSTGRES_DB=origin DATABASE_URL=postgresql://postgres:你的强密码@db:5432/origin?schema=public ``

注意：

POSTGRES_PASSWORD 与 DATABASE_URL 里的密码要相同
密码尽量用字母数字；含 @ # : % / 时，DATABASE_URL 需做 URL 编码
必须在第一次启动之前改好；启动后只改 .env 不会改掉库里已有密码

3.5 确认版本三行与本 zip 一致

一般与 .env.example 相同即可，不要擅自改高：

``env ORIGIN_VERSION=… ORIGIN_DOCKER_IMAGE=…/origin-web:… ORIGIN_MIGRATE_DOCKER_IMAGE=…/origin-migrate:… ``

3.6 部署路径（目录不是默认路径时必改）

``env ORIGIN_HOST_DEPLOY_DIR=/www/wwwroot/origin ``

3.7 建议保留的默认项（一般不用改）

``env ORIGIN_PORT=9620 INTERNAL_APP_ORIGIN=http://127.0.0.1:3000 REDIS_URL=redis://redis:6379 ``

注意：INTERNAL_APP_ORIGIN 填容器内端口 3000，不是宿主机 9620。

保存 .env → 进入第四步。

---

第四步：启动服务

``bash cd /www/wwwroot/origin ``

国内机（推荐一键）：

``bash chmod +x ode scripts/*.sh sh scripts/first-deploy.sh ``

脚本会：检查配置 → 处理宝塔路径 / Docker config → 拉镜像 → 启动 → 打印状态。

一键失败时可手动（仍在同一目录）：

``bash sudo sh scripts/ensure-docker-config.sh sudo sh scripts/ensure-baota-compose-paths.sh docker compose pull docker compose up -d ``

美国/海外机：不要用上面国内一键时的默认 compose，改用文中 [美国 / 海外](#美国--海外服务器us) 一节的命令。

启动完成后 → 进入第五步。

---

第五步：验收容器与健康检查

``bash cd /www/wwwroot/origin docker compose ps ``

正常大致为：

| 服务 | 期望状态 | |------|----------| | db / redis | running (healthy) | | web / updater | running | | migrate | exited (0) ← 一次性任务，退出码 0 表示迁移成功（不是故障） |

健康检查：

``bash curl -sS http://127.0.0.1:9620/api/health ``

期望看到类似 status ok、database connected，且 version 与 .env 中 ORIGIN_VERSION 一致。（不要在公网直接访问 9620。）

出问题再看日志：

``bash docker compose logs --tail=80 web docker compose logs --tail=80 migrate ``

验收通过 → 进入第六步。新站一般不需要单独再跑 migrate 或 recover-update。

---

第六步：宝塔网站 + 反向代理 + HTTPS

6.1 添加站点

1. 宝塔 → 网站 → 添加站点 2. 域名填你的实际域名 3. PHP 可选「纯静态」（页面由 Docker 提供）

6.2 反向代理

1. 进入该站点 → 反向代理 → 添加反向代理 2. 目标 URL：http://127.0.0.1:9620 3. 发送域名建议：$host

高级/自定义配置中建议包含：

``nginx 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; ``

6.3 发帖图片不显示时（推荐一并配置）

若图片 URL 为 /uploads/... 但浏览器 404，在站点「配置文件」里、其它静态图片规则之前增加：

``nginx location ^~ /uploads/ { proxy_pass http://127.0.0.1:9620; 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; } ``

保存后重载 Nginx。

6.4 申请 SSL

站点 → SSL → Let's Encrypt（或上传证书）→ 开启「强制 HTTPS」。务必用 https://域名 访问，不要用 http://IP:9620 登录（Cookie 可能失效）。

6.5 若使用宝塔「Docker → 容器编排」

Compose 文件路径只填一行（不要逗号拼两段）：

``text /www/wwwroot/origin/docker-compose.yml ``

核对：

```bash cd /www/wwwroot/origin sh scripts/print-baota-path.sh

或

cat baota-compose.path ```

报「文件不存在 / 双路径」：

``bash cd /www/wwwroot/origin sudo sh scripts/ensure-baota-compose-paths.sh ``

面板「暂无容器」但 docker compose ps 正常 → 以命令行为准。详见同目录：宝塔编排路径.txt

完成后 → 进入第七步。

---

第七步：注册管理员并进入后台

1. 浏览器打开：https://你的域名/register 2. 注册第一个「真人」账号 → 自动成为管理员 3. 再进入后台管理

忘记用户名或密码时，在部署目录：

``bash cd /www/wwwroot/origin ./ode list-admins ./ode reset-admin-password ``

若注册后仍是普通用户，可在部署目录提权（把用户名换成你的）：

``bash cd /www/wwwroot/origin docker compose exec db psql -U postgres -d origin -c \ "UPDATE \"User\" SET role = 'ADMIN' WHERE username = '你的用户名';" ``

然后重新登录再进后台。

---

部署完成检查清单

[ ] 已解压到 /www/wwwroot/origin（或自定路径，且 ORIGIN_HOST_DEPLOY_DIR 一致）
[ ] Docker / Compose 已安装并运行；建议关闭宝塔系统防火墙
[ ] 已 cp 模板为 .env，并改好两个密钥与 NEXT_PUBLIC_APP_URL
[ ] 已改 POSTGRES_PASSWORD，并与 DATABASE_URL 密码一致（首次启动前）
[ ] ORIGIN_VERSION 与两个镜像 tag 一致，且与本 zip 一致
[ ] INTERNAL_APP_ORIGIN=http://127.0.0.1:3000
[ ] 已执行 first-deploy（或手动 up -d）
[ ] docker compose ps：db/redis healthy，web/updater running，migrate exited (0)
[ ] curl 127.0.0.1:9620/api/health 正常
[ ] 宝塔反代 → 127.0.0.1:9620，SSL 已开；（推荐）已配 /uploads/ 代理
[ ] https://域名/register 可注册，并可进入后台

---

美国 / 海外服务器（US）

在「第三步」用：

``bash cd /www/wwwroot/origin cp .env.us.example .env ``

按第三步改密钥、域名、数据库密码后，用下面代替「第四步」的国内一键：

``bash docker compose -f docker-compose.us.yml pull docker compose -f docker-compose.us.yml up -d ``

宝塔编排路径可填：

``text /www/wwwroot/origin/docker-compose.us.yml ``

之后凡 docker compose 命令，请同样加上：

``bash -f docker-compose.us.yml ``

---

已上线站点如何升级

正常：登录后台 → 系统 → 一键更新。一般不必改 .env。

卡住或失败时（部署目录）：

```bash cd /www/wwwroot/origin ./ode diagnose ./ode migrate ./ode maintenance off

或

sh scripts/recover-update.sh ```

---

日常运维（ode）

工作目录： 部署目录（未 install 时）

``bash cd /www/wwwroot/origin chmod +x ode ./ode origin # 打开菜单（推荐） ``

常用子命令

| 命令 | 说明 | |------|------| | ./ode diagnose | 一键诊断（状态 + web/migrate 日志） | | ./ode status | 状态 / 健康检查 | | ./ode logs | 跟随 web 日志（Ctrl+C 退出） | | ./ode migrate | 重试数据库迁移 | | ./ode migrate-logs | 看 migrate 日志 | | ./ode maintenance on\|off | 开/关维护模式 | | ./ode restart-web | 只重启 web | | ./ode pull | 只拉镜像 | | ./ode upgrade [版本] | 手动升级 | | ./ode backup | 备份 | | ./ode backup --archive | 备份并打成 .tar.gz | | ./ode recover [版本] | 修复更新中断 | | ./ode list-admins | 列出管理员 | | ./ode reset-admin-password | 重置管理员密码 | | ./ode unlock-user | 解封用户 / 允许登录 | | ./ode prune | 清理旧版镜像 / 悬空层 | | ./ode cleanup | 清理残留 migrate 容器 | | ./ode baota-fix | 修复宝塔路径 / Docker 配置 | | ./ode install | 装到 PATH（需 root） | | ./ode help | 帮助 |

迁移失败建议顺序：

``bash cd /www/wwwroot/origin ./ode diagnose ./ode migrate ./ode maintenance off ./ode status ``

可选装到系统 PATH（之后任意目录可直接 ode origin）：

``bash cd /www/wwwroot/origin sudo ./ode install ``

---

常见错误说明（对照表）

以下命令如无特殊说明，均先执行：

``bash cd /www/wwwroot/origin ``

拉镜像 / 网络

1. pull access denied（origin-web / origin-migrate） - 现象：docker compose pull 失败，提示 access denied / not found - 处理：核对 .env 版本三行是否与本包一致；不要改成尚未提供的高版本。联系给你包的一方确认该版本镜像是否已发布。

2. registry-1.docker.io 超时（国内机） - 现象：拉 postgres/redis/docker-cli 卡住或超时 - 处理：确认用的是默认 docker-compose.yml（基础镜像走国内代理）；或在 Docker 配置 registry-mirrors 后重试 docker compose pull。

3. DaoCloud / 国内代理超时（美国机） - 现象：国内代理镜像反而拉不动 - 处理：改用 [美国 / 海外](#美国--海外服务器us) 模板（.env.us.example + docker-compose.us.yml）。

Docker 配置 / 数据库起不来

4. config.json is a directory / Error loading config file … config.json

``bash sudo sh scripts/ensure-docker-config.sh docker compose up -d updater ``

5. postmaster.pid / pg_wal … Operation not permitted；db unhealthy - 确认 docker-compose.yml 的 db 含 security_opt: seccomp:unconfined - 检查云主机安全软件是否拦截 Docker - 新站且无重要数据时，可停栈后清 Postgres 数据卷再重新 first-deploy（会清空库，慎用）

6. dependency failed … origin-db-1 is unhealthy 先按第 5 条修好 db，再：

``bash docker compose up -d ``

7. web 一直 Waiting / Restarting 看 db、redis 是否 healthy；确认 REDIS_URL=redis://redis:6379；

``bash docker compose logs --tail=100 web ``

迁移 migrate

8. migrate 失败 / password authentication failed 核对 POSTGRES_* 与 DATABASE_URL 是否一致；若数据卷已初始化过，只改 .env 无效，需进库改密码或按备份流程处理。

9. migrate 失败（其它）/ prisma 相关报错 确认 ORIGIN_MIGRATE_DOCKER_IMAGE 指向 origin-migrate（不要填成 web 镜像）：

``bash docker compose logs --tail=120 migrate ./ode migrate ``

10. 一键更新后登录提示「数据库未就绪」或功能异常

``bash ./ode diagnose ./ode migrate ./ode maintenance off ./ode restart-web ``

宝塔编排 / 面板

11. 宝塔提示 compose 文件不存在（双路径）

``bash sudo sh scripts/ensure-baota-compose-paths.sh ``

面板只填一行：/www/wwwroot/origin/docker-compose.yml 勿删除编排项目（可能停栈或清卷）；以 docker compose ps 为准。详见 宝塔编排路径.txt。

12. 宝塔编排显示「运行中」但「暂无容器」 以 SSH 里 docker compose ps 为准；面板常不同步命令行拉起的栈，不必为此反复点删除重建。

网站访问 / 登录 / 图片

13. 502 Bad Gateway

``bash docker compose ps curl -sS http://127.0.0.1:9620/api/health ``

确认反代目标是 http://127.0.0.1:9620。

14. 登录后跳回登录页 / Cookie 无效 必须用 https://域名 访问；不要用 http://IP:9620；确认已开强制 HTTPS，且 NEXT_PUBLIC_APP_URL 与访问域名一致。

15. 发帖图片 404 按第六步 6.3 配置 /uploads/ 反代到 9620；本机可先测：

``bash curl -I http://127.0.0.1:9620/api/health ``

16. 健康检查失败 / 域名打不开站

``bash docker compose ps docker compose logs --tail=100 web docker compose logs --tail=100 migrate ``

确认 DNS、SSL、反代均指向本机 9620。

维护模式 / 更新卡住

17. 整站提示维护中、关不掉

```bash ./ode maintenance off

或编辑 .env 将 MAINTENANCE_MODE=false 后：

docker compose up -d web ```

18. 一键更新失败 / 卡在更新中

``bash ./ode diagnose ./ode migrate ./ode maintenance off sh scripts/recover-update.sh ``

防火墙 / 容器反复退出

19. web 反复 Restarting (137)；或日志出现 No chain/target/match 关闭宝塔「系统防火墙」后：

``bash sudo systemctl restart docker cd /www/wwwroot/origin && docker compose up -d ``

入站只靠云安全组开放 80、443、22。

20. 检查更新 / 拉取更新说明失败 确认服务器能访问更新源（.env 中 ORIGIN_RELEASES_URL）；不要把更新源与本站配成「域名解析回本机公网 IP」的死循环（Hairpin NAT）。

账号

21. 忘记管理员密码

``bash ./ode list-admins ./ode reset-admin-password ``

22. 账号被封 / 无法登录

``bash ./ode unlock-user ``

---

常用 Docker 命令备忘

```bash cd /www/wwwroot/origin

docker compose ps docker compose logs -f web docker compose logs --tail=50 db docker compose restart web docker compose pull docker compose up -d ```

美国/海外把上面的 docker compose 换成：

``bash docker compose -f docker-compose.us.yml … ``