# 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`。

---

**文档状态**：适用于主项目单站部署与本机开发；多服务架构以永平版文档为准。