3.4 KiB
3.4 KiB
Soul 主站 · 本机运行文档
主项目（一场soul的创业实验）本机与服务器运行说明。永平版多服务架构见「永平版优化对比与合并说明」中的本机运行文档参考。
一、主项目运行架构（单 Next 站）
1.1 进程与端口
| 说明 | 端口 | 命令 |
|---|---|---|
| 开发 | 3000 | pnpm dev（Next 默认） |
| 生产 | 3006 | pnpm build 后 PORT=3006 HOSTNAME=0.0.0.0 node .next/standalone/server.js |
1.2 目录与部署
- 本地开发：根目录即 Next 源码，
app/、lib/、components/、book/、miniprogram/同层。 - 生产部署：小型宝塔 42.194.232.22，项目路径
/www/wwwroot/soul，PM2 进程名soul，端口 3006。
二、本机运行步骤
2.1 安装依赖
pnpm install
2.2 开发模式
pnpm dev
- 默认端口 3000，可在
package.json或环境变量中指定PORT=3006。 - 访问：http://localhost:3000（或 http://localhost:3006）
2.3 生产模式（本地模拟）
pnpm build
PORT=3006 HOSTNAME=0.0.0.0 node .next/standalone/server.js
- 需先完成
pnpm build，standalone 输出在.next/standalone/。 - 环境变量：
.env.local中配置MYSQL_*（可选）、SKIP_DB（本地无 DB 时可设SKIP_DB=1，部分接口会报错，适合纯前端联调）。
2.4 数据库
- 默认使用腾讯云 MySQL（见
lib/db.ts默认值）。 - 本地无数据库时：设置
SKIP_DB=1，接口中依赖 DB 的会抛错，可配合 Mock 或仅跑静态页。 - 环境变量覆盖：
MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE。
三、关键配置
3.1 环境变量（.env.local）
| 配置项 | 说明 |
|---|---|
| MYSQL_HOST / MYSQL_PORT / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE | 数据库连接，不设则用代码默认值 |
| SKIP_DB | 设为 1 或 true 时跳过 DB 连接，适合无 DB 环境 |
| ADMIN_USERNAME / ADMIN_PASSWORD | 后台管理员账号密码（默认 admin / key123456） |
| ADMIN_SESSION_SECRET | 管理员 Cookie 签名密钥（生产建议修改） |
3.2 管理后台
- 登录：http://localhost:3000/admin/login（开发）或 /admin/login（生产）
- 默认账号：admin / key123456（与 .cursorrules 一致，可通过环境变量覆盖）
- 登出 API：
POST /api/admin/logout（清除管理员 Cookie，可与「退出登录」按钮对接）
四、与永平版差异
- 永平版：多服务（Go API 8080、Vue 管理后台 5174、Next 主站 3006），见永平根目录
本机运行文档.md。 - 本主项目：单 Next 应用，无独立 Go/Vue，管理后台为 Next 内
/admin，API 为 Next 内/api/*。 - CORS：主项目在
middleware.ts与next.config.mjs中配置；永平可能由 Nginx/Go 处理。
五、常见问题
-
端口被占用
修改启动命令：PORT=3007 pnpm dev或PORT=3007 node .next/standalone/server.js -
数据库连接失败
检查.env.local中MYSQL_*及本机网络是否能访问腾讯云 MySQL；或设SKIP_DB=1做无 DB 联调。 -
API 跨域
主项目已通过middleware.ts为/api/:path*设置 CORS，允许来源见ALLOWED_ORIGINS。
文档状态：适用于主项目单站部署与本机开发；多服务架构以永平版文档为准。