99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# 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 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 2.2 开发模式
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
- 默认端口 3000，可在 `package.json` 或环境变量中指定 `PORT=3006`。
|
||
- 访问：http://localhost:3000（或 http://localhost:3006）
|
||
|
||
### 2.3 生产模式（本地模拟）
|
||
|
||
```bash
|
||
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 处理。
|
||
|
||
---
|
||
|
||
## 五、常见问题
|
||
|
||
1. **端口被占用**
|
||
修改启动命令：`PORT=3007 pnpm dev` 或 `PORT=3007 node .next/standalone/server.js`
|
||
|
||
2. **数据库连接失败**
|
||
检查 `.env.local` 中 `MYSQL_*` 及本机网络是否能访问腾讯云 MySQL；或设 `SKIP_DB=1` 做无 DB 联调。
|
||
|
||
3. **API 跨域**
|
||
主项目已通过 `middleware.ts` 为 `/api/:path*` 设置 CORS，允许来源见 `ALLOWED_ORIGINS`。
|
||
|
||
---
|
||
|
||
**文档状态**：适用于主项目单站部署与本机开发；多服务架构以永平版文档为准。
|