若白 RuoBai 萌新部署教程：从 0 到跑起来

这篇是给第一次部署若白的人看的。你不需要懂太多代码，按顺序做，一步一步来就行。
文中的域名、路径、数据库名、密码都是示例，请换成你自己的。不要把真实密码、API Key、聊天记录上传到公开仓库。

零、最简单的方式：Docker 一条命令

如果你是宝塔用户，最简单的方式是：先在宝塔软件商店安装 Docker，然后打开宝塔终端，粘贴一条命令。

把下面的 ruobai.example.com 换成你自己的域名：

DOMAIN=ruobai.example.com bash -c "$(curl -fsSL https://raw.githubusercontent.com/lshl-520/RuoBai/main/scripts/install-docker.sh)"

这条命令会自动做这些事：

从 GitHub 拉取若白代码。
生成 Docker 配置和随机数据库密码。
编译 React 前端。
启动 MariaDB 数据库容器。
启动若白网站容器。
初始化数据库。
最后在终端打印访问地址、后台地址、默认管理员账号和默认密码。

脚本默认把网站跑在服务器本机：

http://127.0.0.1:3000

宝塔里把你的域名反向代理到这个地址就行。这样做是为了不直接把 Node 服务暴露到公网，也避免脚本乱改你服务器上已有的博客和其他站点。

默认管理员是：

用户名：admin
密码：123456

第一次登录后，必须马上进入后台把默认密码改掉。

如果你想一起启动向量记忆容器，用下面这条：

ENABLE_VECTOR=1 DOMAIN=ruobai.example.com bash -c "$(curl -fsSL https://raw.githubusercontent.com/lshl-520/RuoBai/main/scripts/install-docker.sh)"

第一次部署建议先不要开向量记忆。先让网站跑起来，再慢慢加长期记忆。

如果你不用 Docker，也可以继续看下面的手动部署步骤。

一、你需要先准备什么

部署若白之前，先准备好这些东西：

一台服务器，推荐 2 核 2G 起步。
一个域名，并且已经解析到服务器。
宝塔面板或自己会配置 Nginx。
Node.js 20 或更新版本。
MariaDB 或 MySQL 数据库。
pm2，用来让网站后台一直运行。
可选：Docker。只有你想启用“向量记忆”时才需要。

如果你只是想先把网站跑起来，Docker 可以先不装。没有向量记忆时，聊天功能仍然能用，只是角色暂时不能从很久以前的聊天里自动找回回忆。

二、拉取若白代码

登录服务器后，进入你准备放网站的目录。下面用 /www/wwwroot/ruobai 举例，你可以换成自己的路径。

cd /www/wwwroot
git clone https://github.com/lshl-520/RuoBai.git ruobai
cd ruobai

注意：公开仓库里不会带你的私密配置。.env、聊天图片、API Key、服务器密码都不应该进 git。

三、安装后端依赖

cd /www/wwwroot/ruobai/server
npm install

如果服务器网络慢，可以多等一会儿。不要中途关掉窗口。

四、安装前端依赖并编译

若白现在主界面是 React 版，所以需要先编译前端：

cd /www/wwwroot/ruobai/frontend-react
npm install
npm run build

编译成功后，会出现：

frontend-react/dist/

这个目录就是前端页面的正式文件。

五、配置数据库和私密配置

进入后端目录，复制一份配置文件：

cd /www/wwwroot/ruobai/server
cp .env.example .env

然后编辑 .env。示例：

DB_HOST=localhost
DB_PORT=3306
DB_USER=ruobai_user
DB_PASSWORD=这里换成你的数据库密码
DB_NAME=ruobai
SESSION_SECRET=这里换成一串很长的随机字符
PORT=3000
CORS_ORIGINS=https://你的域名,https://www.你的域名
BETA_REGISTRATION_ENABLED=true
OPEN_SOURCE_SINGLE_USER=false

这里最重要的是：

DB_USER 和 DB_PASSWORD 要和你的数据库账号一致。
DB_NAME 是若白使用的数据库名。
SESSION_SECRET 不要用示例文字，随便生成一串长一点的随机字符。
.env 绝对不要提交到 GitHub。

六、初始化数据库

确认数据库已经创建好后，运行：

cd /www/wwwroot/ruobai/server
node init-db.js

这一步会创建若白需要的数据表，比如用户、角色、聊天消息、记忆、动态等。

如果这是第一次部署，系统会创建默认管理员账号。部署完成后请立刻登录后台修改密码。

七、用 pm2 启动后端

在项目根目录启动：

cd /www/wwwroot/ruobai
pm2 start ecosystem.config.js
pm2 save

查看是否运行成功：

pm2 list

看到 ruobai 是 online，就说明后端已经跑起来了。

也可以测试健康接口：

curl http://127.0.0.1:3000/healthz

正常会看到类似：

{"status":"ok"}

八、配置 Nginx 或宝塔反向代理

如果你用宝塔，可以在网站设置里配置反向代理。核心目标是：

访问你的域名时，转发到 127.0.0.1:3000。
开启 HTTPS。
不要暴露 .env、.git、数据库备份等私密文件。

Nginx 示例：

server {
    listen 80;
    server_name 你的域名 www.你的域名;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name 你的域名 www.你的域名;

    ssl_certificate /你的证书路径/fullchain.pem;
    ssl_certificate_key /你的证书路径/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }

    location ~ ^/(\.env|\.git|README.md|LICENSE) {
        return 404;
    }
}

如果你使用“静态目录 + API 代理”的方式，也可以把网站根目录指向 frontend-react/dist，然后把 /api 和 /user_assets 转发到 127.0.0.1:3000。两种方式选一种，不要混乱配置。

九、可选：开启向量记忆

向量记忆能让角色从长期聊天记录里找回相关内容。它需要 Docker。

启动 Qdrant：

docker run -d --name ruobai-qdrant \
  -p 6333:6333 \
  -v ruobai_qdrant_storage:/qdrant/storage \
  qdrant/qdrant

启动中文向量模型服务：

docker run -d --name ruobai-embedding \
  -p 8090:80 \
  ghcr.io/huggingface/text-embeddings-inference:cpu-1.6 \
  --model-id BAAI/bge-small-zh-v1.5 --port 80

然后在 server/.env 里确认：

VECTOR_QDRANT_URL=http://127.0.0.1:6333
VECTOR_EMBEDDING_URL=http://127.0.0.1:8090
VECTOR_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
VECTOR_COLLECTION=ruobai_memories_local

如果你刚开始部署，可以先跳过这一节。等网站稳定后再开向量记忆。

十、部署后检查清单

部署完成后，按这个顺序检查：

打开首页，看页面是否正常显示。
打开后台，看能不能登录。
注册或登录一个用户。
创建一个角色。
发送一条文字消息。
如果配置了模型密钥，测试 AI 是否能回复。
上传一张头像或图片，确认 user_assets 能正常访问。
如果开了向量记忆，再检查 Qdrant 和 embedding 容器是否运行。

十一、第一次登录后怎么填写接口

部署完成后，不要急着聊天。先做两件事：

打开后台，把默认管理员密码改掉。
登录前台，进入“我的 → 接口渠道”，填写你自己的模型接口。

1. DeepSeek 官方接口

适合想先稳定跑起来的人。

服务商类型：DeepSeek / OpenAI 兼容
API 地址：https://api.deepseek.com
模型：deepseek-chat
密钥：填你自己的 DeepSeek Key

如果你想用推理模型，可以把模型改成：

deepseek-reasoner

注意：Key 只填在自己的网站后台里，不要发到评论区，也不要截图给别人。

2. 赞助中转接口

如果你用赞助中转，服务商类型一般选“OpenAI 兼容”。

服务商类型：OpenAI 兼容
接口域名：https://maolaoapi.com
API 地址：按中转后台给出的完整地址填写
模型：选择中转后台里可用的模型
密钥：填你自己的中转 Key

这里可以顺带感谢一下猫佬中转：它赞助过我中转月卡，帮我完善若白的模型调试和日常测试。
但它不是强绑定，你也可以换成 DeepSeek 官方、OpenAI 兼容接口，或者任何你自己信任的服务商。

十二、常见问题

1. 网站 502

先检查后端有没有启动：

pm2 list
pm2 logs ruobai
curl http://127.0.0.1:3000/healthz

如果 healthz 都打不开，说明 Node 后端没跑起来，先看日志。

2. 页面打开了，但接口报错

检查 .env 里的数据库配置是否正确。再检查数据库是否已经初始化：

cd /www/wwwroot/ruobai/server
node init-db.js

3. React 页面没更新

确认你已经执行过：

cd /www/wwwroot/ruobai/frontend-react
npm run build

只 git pull 不够，前端改动通常还需要重新 build。

4. 图片打不开

确认 Nginx 没有拦截 /user_assets，并且后端能访问项目里的 user_assets 目录。

5. 不要公开这些东西

这些内容不要发到公开仓库，也不要截图发给别人：

server/.env
数据库密码
API Key
服务器 SSH 密码或私钥
聊天记录
用户上传图片
数据库备份文件

十三、以后更新代码

常规更新流程：

cd /www/wwwroot/ruobai
git pull
cd server
npm install
node init-db.js
cd ../frontend-react
npm install
npm run build
cd ..
pm2 reload ruobai

如果只是后端小改动，前端没变，可以不跑前端 build。但萌新不确定时，完整跑一遍最稳。

结尾

若白不是一个复杂商业系统。它的核心目标很简单：让普通人也能拥有一个自己可控、可部署、不会被平台随便拿走的 AI 陪伴项目。

第一次部署会有点麻烦，但只要你按顺序做完一次，后面更新就会简单很多。

#若白 #部署教程 #开源

版权属于：江湖小白

本文链接：https://blog.lshl.bid/index.php/archives/21/

本站未注明转载的文章均为原创，并采用 CC BY-NC-SA 4.0 授权协议，转载请注明来源，谢谢！