freefire
fde5f628ec
浏览器登录改为 DB sessions（可吊销）；敏感词与 OIDC PEM 入 settings； 落地安装向导、注册发帖与 /admin 仪表盘/板块/审核/设置。 Co-authored-by: Cursor <cursoragent@cursor.com>
214 lines
7.2 KiB
Markdown
214 lines
7.2 KiB
Markdown
# 07 · 配置、运维与 SEO
|
||
|
||
> **读者**：部署与运维、以及实现配置层的 AI
|
||
> **前置**：[README.md](README.md)
|
||
> **源码**：[`config/`](../../config/)、[`README.md`](../../README.md)、[`routers/api/seo.go`](../../routers/api/seo.go)、[`routers/install/`](../../routers/install/)
|
||
|
||
运维形态可改；下列描述**本分支**行为。
|
||
|
||
---
|
||
|
||
## 0. 首次安装（Gitea 式）
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 锁文件 | `data/install.lock` |
|
||
| 向导 | `GET/POST /install`（`templates/install.tmpl`） |
|
||
| 未锁定 | 除 `/install`、`/ssr-assets/*`、`/health` 外重定向到向导 |
|
||
| 管理员 | 仅安装向导创建；不再「首个注册用户变管理员」 |
|
||
| 向导内容 | 站点名 + 管理员账号（数据库已在进程启动时连上） |
|
||
| 旧数据 | 启动时若已有用户且无锁，自动补写锁 |
|
||
|
||
**无 `app.ini`。** 引导仅 CLI / Env。
|
||
|
||
---
|
||
|
||
## 1. 配置分层与重启边界
|
||
|
||
| 层 | 存什么 | 变更方式 | 需重启 |
|
||
|----|--------|----------|--------|
|
||
| **Bootstrap** | `DATA`、`HTTP_PORT`/`ADDR`、`DB_TYPE` + DSN/连接参数、工作目录 | CLI / Env | **是** |
|
||
| **密钥文件** | App HMAC（`data/.jwt_secret`，文件名历史遗留）；OIDC RSA **仅启用时**写入 settings（可选遗留文件迁移） | 自动生成 | HMAC 换钥需重启 |
|
||
| **站点运行时** | 品牌、邮件、OIDC 开关、限流、敏感词、存储、伪静态… | DB `forum_settings` | **否**（热更） |
|
||
|
||
**优先级：** 命令行显式参数 > 环境变量 > 内置默认。
|
||
|
||
### 进程引导
|
||
|
||
| CLI | 环境变量 | 默认 | 说明 |
|
||
|-----|----------|------|------|
|
||
| `--port` | `JIANG13_HTTP_PORT` | 3000 | 监听端口 |
|
||
| `--http-addr` | `JIANG13_HTTP_ADDR` | （空=全接口） | 监听地址 |
|
||
| `--data` | `JIANG13_DATA` | `data` | 数据目录 |
|
||
| `--work-path` | `JIANG13_WORK_PATH` | 可执行文件目录 | 工作目录 |
|
||
| `--db-type` | `JIANG13_DB_TYPE` | `sqlite` | `sqlite` \| `postgres` \| `mysql` |
|
||
| `--db-dsn` | `JIANG13_DB_DSN` | （sqlite 默认 `{DATA}/jiang13.db`） | 完整 DSN，优先 |
|
||
| `--db-host` 等 | `JIANG13_DB_HOST` / `USER` / `PASS` / `NAME` / `SSLMODE` | | DSN 为空时拼接（pg/mysql） |
|
||
| `--service` | | | install/uninstall/start/stop/restart/status |
|
||
|
||
`{DATA}/.jwt_secret`：**App HMAC 密钥**（CSRF 双提交等），启动时自动生成。**不是**浏览器登录 JWT。`--config` / `--jwt-secret` / `JIANG13_JWT_SECRET` 已废弃。
|
||
|
||
浏览器登录：DB `sessions` + Cookie `jiang13_session`。OIDC 对外 token 仍为 JWT，私钥在 `forum_settings.oidc_rsa_private_pem`（启用时懒加载；未启用不生成 `.oidc_rsa.pem`）。
|
||
|
||
业务配置（邮件、OIDC、存储、品牌、敏感词等）在 **DB `forum_settings`**，管理后台热更新。
|
||
|
||
### 数据库 Env 示例
|
||
|
||
**SQLite（默认）：**
|
||
|
||
```bash
|
||
JIANG13_DATA=/data
|
||
# 可不设 DB_*；库文件 = $JIANG13_DATA/jiang13.db
|
||
```
|
||
|
||
**PostgreSQL：**
|
||
|
||
```bash
|
||
JIANG13_DB_TYPE=postgres
|
||
JIANG13_DB_DSN="postgres://forum:secret@db:5432/jiang13?sslmode=disable"
|
||
# 或拆分：
|
||
# JIANG13_DB_HOST=db:5432
|
||
# JIANG13_DB_USER=forum
|
||
# JIANG13_DB_PASS=secret
|
||
# JIANG13_DB_NAME=jiang13
|
||
# JIANG13_DB_SSLMODE=disable
|
||
```
|
||
|
||
**MySQL / MariaDB：**
|
||
|
||
```bash
|
||
JIANG13_DB_TYPE=mysql
|
||
JIANG13_DB_DSN="forum:secret@tcp(db:3306)/jiang13?parseTime=true&loc=Local&charset=utf8mb4"
|
||
```
|
||
|
||
连库失败时进程**退出并打印 Env 提示**，不会静默回落 sqlite。
|
||
|
||
### Docker Compose 多库示意
|
||
|
||
```yaml
|
||
services:
|
||
jiang13:
|
||
image: hangzhang714128/jiang13-forum:latest
|
||
environment:
|
||
JIANG13_DB_TYPE: postgres
|
||
JIANG13_DB_DSN: postgres://forum:secret@postgres:5432/jiang13?sslmode=disable
|
||
volumes:
|
||
- jiang13-data:/data
|
||
depends_on: [postgres]
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
environment:
|
||
POSTGRES_USER: forum
|
||
POSTGRES_PASSWORD: secret
|
||
POSTGRES_DB: jiang13
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 数据目录结构
|
||
|
||
```text
|
||
data/
|
||
├── install.lock # 安装完成锁（与 DB 引擎无关）
|
||
├── jiang13.db # 仅 SQLite 时的主库文件（含 sessions / forum_settings）
|
||
├── jiang13.log # 运行日志
|
||
├── filter_words.txt # 遗留：启动时可导入 settings；新源以 DB 为准
|
||
├── .jwt_secret # App HMAC（CSRF 等；勿提交；非登录 JWT）
|
||
├── .oidc_rsa.pem # 遗留：仅启用 OIDC 且从文件迁移时可能存在；新站优先 DB
|
||
├── uploads/
|
||
│ ├── avatars/
|
||
│ ├── posts/
|
||
│ └── site/
|
||
└── jiang13_backup_*.db # SQLite 一键备份（其它引擎请用库方工具）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 部署方式（现网）
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| 单二进制 | `build.bat` / `make build` → `dist/jiang13(.exe)` |
|
||
| Docker | 镜像挂载 `/data`；健康检查 `GET /health` |
|
||
| Compose | `docker compose up -d --build` |
|
||
| systemd / Windows Service | `--service install` 后启停 |
|
||
|
||
构建约定见 [`.cursor/rules/build-scripts.mdc`](../../.cursor/rules/build-scripts.mdc)：Windows 用 `build.bat`，勿直接 `make` / `.\build.ps1`。
|
||
|
||
---
|
||
|
||
## 4. 存储后端
|
||
|
||
| type | 行为 |
|
||
|------|------|
|
||
| `local` | 文件落在 `data/uploads`；URL 通常 `/uploads/...` |
|
||
| `s3` | S3 兼容；endpoint、bucket、密钥、public_base_url、prefix、force_path_style |
|
||
|
||
`image_delivery`：`webp`（默认，经 `/media/thumb`）或 `original`。
|
||
|
||
媒体索引表 `media` 供后台列表；启动时可后台 SyncMediaIndex。
|
||
|
||
---
|
||
|
||
## 5. SEO / 社交分享字段集合
|
||
|
||
新站应用真 SSR，但 **meta 字段应对齐**：
|
||
|
||
| 字段 | 来源 |
|
||
|------|------|
|
||
| `<title>` | 站点 DocumentTitle 或帖标题 |
|
||
| meta description | 站点简介优先，否则标语；帖文则摘要 |
|
||
| meta keywords | 站点 keywords |
|
||
| canonical | 绝对 URL |
|
||
| og:* / twitter:* | |
|
||
| JSON-LD | 结构化数据 |
|
||
| robots | 个别页可 noindex |
|
||
|
||
| 机制 | 说明 |
|
||
|------|------|
|
||
| robots.txt / sitemap.xml | 动态生成 |
|
||
|
||
重构验收：普通浏览器「查看网页源代码」应能看到帖文正文。
|
||
|
||
---
|
||
|
||
## 6. 伪静态 Permalink
|
||
|
||
设置：`permalink_enabled`、`permalink_ext`（默认 `html`）。
|
||
|
||
---
|
||
|
||
## 7. 安全相关运维注意
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| HMAC / OIDC | 勿提交 `.jwt_secret`；OIDC PEM 优先在 DB；遗留 `.oidc_rsa.pem` 亦勿提交 |
|
||
| Cookie | `jiang13_session` HttpOnly + SameSite=Lax；生产 HTTPS 下 Secure |
|
||
| 上传 | 类型/大小限制 |
|
||
| 敏感词 | `forum_settings.filter_words`，后台可改热更 |
|
||
| 备份 | SQLite 文件备份含哈希与私信；PG/MySQL 用官方工具 |
|
||
|
||
---
|
||
|
||
## 8. 健康检查
|
||
|
||
`GET /health` → JSON `status`。DB 不可用时非 200。
|
||
|
||
---
|
||
|
||
## 9. 从旧站迁数据建议
|
||
|
||
1. SQLite：复制 `jiang13.db`；或 dump 到 PG/MySQL 并映射表
|
||
2. 复制 `uploads/`、`.jwt_secret`（HMAC 兼容）；敏感词若仍在文件可启动导入
|
||
3. 迁移 `forum_settings` 或后台重配（含 `filter_words`）
|
||
4. OIDC：`oauth_clients` + settings 中 PEM（或遗留 `.oidc_rsa.pem` 一次迁移）
|
||
5. 旧站 JWT Cookie 无效；用户需重新登录（opaque session）
|
||
|
||
表语义以 [03-data-model.md](03-data-model.md) 为准。
|
||
|
||
---
|
||
|
||
## 10. 文档包索引
|
||
|
||
返回 [README.md](README.md) 阅读顺序；功能验收用 [02-features.md](02-features.md)；规则用 [05-business-rules.md](05-business-rules.md)。
|