195 lines
5.0 KiB
Markdown
195 lines
5.0 KiB
Markdown
# 服务配置说明
|
||
|
||
支付、PocketBase、MinIO 存储已组件化、配置化，可通过环境变量和主题配置覆盖。
|
||
|
||
## 配置入口
|
||
|
||
- **`config/services.config.ts`** - 服务配置
|
||
- **`config/site.config.ts`** - 主题可覆盖 `services` 字段
|
||
|
||
## PocketBase
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `NEXT_PUBLIC_POCKETBASE_URL` | 客户端可见的 PB 地址 | https://pocketbase.hackrobot.cn |
|
||
| `POCKETBASE_URL` | 服务端 PB 地址 | 同上 |
|
||
| `POCKETBASE_JOIN_COLLECTION` | 申请表单集合名 | solan |
|
||
| `POCKETBASE_EMAIL` | 管理员邮箱（创建记录用） | - |
|
||
| `POCKETBASE_PASSWORD` | 管理员密码 | - |
|
||
|
||
### 主题覆盖
|
||
|
||
在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：
|
||
|
||
```ts
|
||
services: {
|
||
pocketbaseJoinCollection: "solan", // 申请/加入表单集合
|
||
},
|
||
```
|
||
|
||
### 使用方式
|
||
|
||
```ts
|
||
import { pbLogin, pbRegister, pbSaveAuth, pbLogout, getStoredUserEmail } from "@/app/lib/pocketbase";
|
||
|
||
// 登录
|
||
const result = await pbLogin(email, password);
|
||
pbSaveAuth(result.token, result.record);
|
||
|
||
// 注册
|
||
const result = await pbRegister(email, password, passwordConfirm);
|
||
pbSaveAuth(result.token, result.record);
|
||
|
||
// 登出
|
||
pbLogout();
|
||
|
||
// 获取当前用户邮箱
|
||
const email = getStoredUserEmail();
|
||
```
|
||
|
||
## 支付
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `PAYMENT_API_URL` | payjsapi 地址 | 开发: 127.0.0.1:8700 / 生产: api.hackrobot.cn |
|
||
| `PAYMENT_PROVIDER` | 支付提供商 | zpay |
|
||
| `PAYMENT_DEFAULT_AMOUNT` | 默认金额（分） | 80 |
|
||
| `PAYMENT_DEFAULT_TYPE` | 默认订单类型 | meetup |
|
||
| `ZPAY_SUBMIT_URL` | ZPAY 提交地址 | https://zpayz.cn/submit.php |
|
||
|
||
### 主题覆盖
|
||
|
||
在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：
|
||
|
||
```ts
|
||
services: {
|
||
join: {
|
||
amount: 80, // 加入费用（分）
|
||
type: "meetup", // 订单类型
|
||
},
|
||
},
|
||
```
|
||
|
||
### 使用方式
|
||
|
||
```ts
|
||
import {
|
||
getPayEnv,
|
||
getRecommendedChannel,
|
||
mustUseWxPay,
|
||
redirectToPay,
|
||
getDeviceFromEnv,
|
||
} from "@/app/lib/payment";
|
||
|
||
// 检测支付环境
|
||
const env = getPayEnv(); // "pc" | "h5" | "wechat"
|
||
const channel = getRecommendedChannel(env);
|
||
const device = getDeviceFromEnv(env);
|
||
|
||
// 发起支付跳转（加入场景，使用主题配置）
|
||
redirectToPay({
|
||
user_id: userId,
|
||
return_url: returnUrl,
|
||
channel,
|
||
device,
|
||
useJoinConfig: true, // 使用主题的 amount/type
|
||
});
|
||
```
|
||
|
||
## MinIO 存储
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `MINIO_ENDPOINT` | 服务端点 | minioweb.hackrobot.cn |
|
||
| `MINIO_PORT` | 端口 | 9035 |
|
||
| `MINIO_USE_SSL` | 是否使用 SSL | false |
|
||
| `MINIO_BUCKET` | 存储桶 | hackrobot |
|
||
| `MINIO_ACCESS_KEY` | Access Key | - |
|
||
| `MINIO_SECRET_KEY` | Secret Key | - |
|
||
| `MINIO_REGION` | 区域 | china |
|
||
| `MINIO_PUBLIC_URL` | 公开访问 URL | https://{endpoint}/{bucket} |
|
||
| `MINIO_UPLOAD_PREFIX` | 上传路径前缀 | joins |
|
||
|
||
### 主题覆盖
|
||
|
||
在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：
|
||
|
||
```ts
|
||
services: {
|
||
minio: {
|
||
bucket: "my-bucket", // 存储桶
|
||
uploadPrefix: "joins", // 上传路径前缀
|
||
},
|
||
},
|
||
```
|
||
|
||
### 使用方式
|
||
|
||
```ts
|
||
import {
|
||
getMinioClient,
|
||
uploadBuffer,
|
||
generateObjectKey,
|
||
} from "@/app/lib/minio";
|
||
|
||
// 上传文件
|
||
const objectKey = generateObjectKey("jpg");
|
||
const { url } = await uploadBuffer(buffer, objectKey, "image/jpeg");
|
||
|
||
// 获取客户端（高级用法）
|
||
const client = getMinioClient();
|
||
```
|
||
|
||
## API 路由
|
||
|
||
- **`/api/join`** - 使用 `getPocketBaseConfig()` 和主题的 `pocketbaseJoinCollection`
|
||
- **`/api/pay`** - 使用 `getPaymentConfig()` 和 `getJoinPaymentConfig()`
|
||
- **`/api/pay/status`** - 使用 `getPaymentConfig()`
|
||
- **`/api/upload-media`** - 使用 `getMinioConfig()` 和主题的 `minio` 配置
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
config/
|
||
services.config.ts # 服务配置
|
||
site.config.ts # 主题配置（含 services 覆盖）
|
||
|
||
app/lib/
|
||
pocketbase/
|
||
auth.ts # 认证：login/register/logout
|
||
constants.ts # 存储 key
|
||
config.ts # 配置导出
|
||
index.ts
|
||
payment/
|
||
client.ts # redirectToPay
|
||
config.ts # 配置导出
|
||
types.ts # PayChannel, PayEnv
|
||
index.ts # 聚合 payEnv
|
||
minio/
|
||
config.ts # 配置导出
|
||
client.ts # getMinioClient, uploadBuffer, generateObjectKey
|
||
index.ts
|
||
```
|
||
|
||
## 缓存与部署更新
|
||
|
||
项目已配置 `Cache-Control: no-store, no-cache`，部署后用户应能立即看到更新。若使用 **Cloudflare**，还需在控制台调整：
|
||
|
||
### Cloudflare 控制台设置
|
||
|
||
1. **Caching → Configuration**
|
||
- **Caching Level**：选 `Standard` 或 `Bypass`（开发/频繁更新时）
|
||
- **Browser Cache TTL**：选 `Respect Existing Headers`，以遵循源站 `Cache-Control`
|
||
|
||
2. **Caching → Cache Rules**（可选）
|
||
- 为 `/*` 添加规则：`Cache eligibility` = Bypass，或 `Edge TTL` = 0
|
||
|
||
3. **DNS**
|
||
- 记录 **TTL**：设为 `1`（Auto）或 `60` 秒，加快 DNS 变更生效
|