📦 操作文档

项目安装

源码、.env、依赖、Prisma、管理员与构建

项目安装#

源码、.env、依赖、Prisma、管理员与构建

7. 上传最终源码#

进入：

宝塔 → 文件 → /www/wwwroot/graduate-os

上传最终源码 ZIP，解压到当前目录。

最终必须直接看到：

/www/wwwroot/graduate-os/package.json
/www/wwwroot/graduate-os/package-lock.json
/www/wwwroot/graduate-os/app/
/www/wwwroot/graduate-os/components/
/www/wwwroot/graduate-os/lib/
/www/wwwroot/graduate-os/prisma/
/www/wwwroot/graduate-os/.env.example
/www/wwwroot/graduate-os/ecosystem.config.cjs

错误：

/www/wwwroot/graduate-os/Graduate-OS/package.json

正确：

/www/wwwroot/graduate-os/package.json

如果多套一层目录，用宝塔文件管理器把内层文件移动到项目根目录。

8. 创建运行目录#

终端：

cd /www/wwwroot/graduate-os
mkdir -p storage/papers logs
chmod 750 storage storage/papers logs

不要：

chmod -R 777 storage

9. 创建 `.env`#

宝塔文件管理器复制：

.env.example

为：

.env

也可以：

cd /www/wwwroot/graduate-os
cp .env.example .env

然后在宝塔文件编辑器打开：

/www/wwwroot/graduate-os/.env

推荐模板：

DATABASE_URL="mysql://graduate_os:你的数据库密码@127.0.0.1:3306/graduate_os"

# 官方 OpenAI 可留空；如果从网站后台配置 Provider，不必在这里填写真实 Key。
OPENAI_API_KEY=""
OPENAI_MODEL="gpt-5.6"
OPENAI_PDF_DETAIL="high"

# 用于加密数据库中的 AI / SerpApi Key。生成一次后永久保留。
SECRET_ENCRYPTION_KEY="填写64位十六进制字符串"

# 后台配置 SerpApi 时可以留空；这里保留兼容回退。
SERPAPI_API_KEY=""

ADMIN_USERNAME="你的系统管理员用户名"
ADMIN_PASSWORD="首次创建管理员时使用的强密码"

SESSION_SECRET="填写随机长字符串"
APP_URL="https://xjtu.example.com"
UPLOAD_DIR="/www/wwwroot/graduate-os/storage/papers"
MAX_PDF_SIZE_MB="40"

AI_ENABLED="true"
SCHOLAR_ENABLED="true"
RADAR_MAX_RESULTS_PER_KEYWORD="20"

PORT="3000"
BACKUP_DIR="/backup/graduate-os"

9.1 生成 SESSION_SECRET#

openssl rand -hex 48

复制输出到：

SESSION_SECRET="..."

9.2 生成 SECRET_ENCRYPTION_KEY#

openssl rand -hex 32

复制输出到：

SECRET_ENCRYPTION_KEY="..."

这个值以后不要重新生成#

后台保存的：

OpenAI API Key
OpenAI Compatible / Sub2API Key
SerpApi Key

会使用它加密。更换该密钥会导致已经保存的密钥无法解密。

9.3 `true` 拼写必须正确#

正确：

AI_ENABLED="true"
SCHOLAR_ENABLED="true"

错误：

AI_ENABLED="ture"
SCHOLAR_ENABLED="ture"

ture 会被程序视为未启用。

9.4 权限#

cd /www/wwwroot/graduate-os
chmod 600 .env

10. 安装 Node 依赖#

cd /www/wwwroot/graduate-os
npm ci

最终整合包已经把真实部署中缺失过的：

server-only@0.0.1

正式写入 package.json 与 package-lock.json，因此新部署不需要再手动 npm install server-only。

检查：

npm ls server-only --depth=0

应看到：

server-only@0.0.1

如果 npm ci 只出现 npm WARN，通常不是失败；真正失败会出现 npm ERR!。

11. 初始化 Prisma 数据库#

执行：

cd /www/wwwroot/graduate-os
npx prisma generate
npx prisma migrate deploy
npx prisma migrate status

当前最终包包含：

20260824000000_init
20260826000000_phase2_task1_ai_provider
20260826010000_phase2_task2_search_provider
20260826020000_phase2_task4_interview_link
20260826030000_phase2_task5b_question_analysis
20260826040000_phase2_task6_question_practice

最后应看到数据库 schema 已是最新。

常见数据库错误#

P1000 / Authentication failed#

数据库账号或密码错误。

检查 .env：

DATABASE_URL="mysql://graduate_os:正确密码@127.0.0.1:3306/graduate_os"

P1001#

MySQL 未启动、地址/端口错误。

P1045#

数据库用户名或密码错误。

绝对不要为了解决连接错误执行：

npx prisma migrate reset
npx prisma db push --force-reset

12. 创建唯一管理员#

执行：

cd /www/wwwroot/graduate-os
npm run admin:create

创建成功后，在 .env 中把：

ADMIN_PASSWORD=""

清空，避免首次密码长期留在配置中。

系统不开放注册，只有一个管理员。

13. 构建 standalone#

cd /www/wwwroot/graduate-os
npm run typecheck
npm run lint
npm run build

npm run build 已包含：

Prisma generate
Next.js build
standalone 资源整理
public/static 同步

检查：

test -f .next/standalone/server.js && echo "server OK"
test -d .next/standalone/.next/static && echo "static OK"
test -d .next/standalone/public && echo "public OK"

应该看到：

server OK
static OK
public OK