# shuoshuo-pro

**Repository Path**: consuy1382/shuoshuo-pro

## Basic Information

- **Project Name**: shuoshuo-pro
- **Description**: 自研类多说评论组件。多站点共用一套后端，单机部署，基于 RuoYi-Vue 3.9.2 基座（Spring Boot 4.1 / JDK 17 / MySQL 8 / Redis）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: sns, 评论组件, 社交, 多说

## README

# Shuoshuo·Pro

自研类多说评论组件。多站点共用一套后端，单机部署，基于 RuoYi-Vue 3.9.2 基座（Spring Boot 4.1 / JDK 17 / MySQL 8 / Redis）。

- **解决什么**：第三方评论服务不可控（停运 / 性能 / 隐私）；多站点要共用一套评论系统但数据彼此隔离；接入成本要低——贴一行 `<script>` 就有评论区。
- **一期定位**：单机部署稳定承载多站点；评论渲染零 XSS；核心链路 P95 < 300ms。

## 文档

全套文档在 [`docs/`](docs/README.md)，入口页按角色分流。速览：

| 从这里开始 | 文档 |
| --- | --- |
| 新人上手（改代码） | [`docs/guide/getting-started.md`](docs/guide/getting-started.md) → [架构](docs/guide/architecture.md) → [开发规范](docs/guide/dev-workflow.md) |
| 站点接入（放评论区） | [`docs/integration/quickstart.md`](docs/integration/quickstart.md)（**读接口鉴权三态必读**） |
| 部署与运维 | [`docs/ops/deployment.md`](docs/ops/deployment.md) · [故障排查 Runbook](docs/ops/runbook.md) |
| API 参考 | [`docs/api/overview.md`](docs/api/overview.md)（逐端点，按源码核对） |
| 产品与规格 | [`docs/product/overview.md`](docs/product/overview.md) · [`docs/spec/overview.md`](docs/spec/overview.md) |
| 路线图 / 架构决策 | [`docs/roadmap.md`](docs/roadmap.md) · [`docs/adr/`](docs/adr/README.md) |

## 目录结构

```
shuoshuo-pro/
├── RuoYi-Vue/                  后端（对应 SPEC §14 的 backend/）
│   ├── ruoyi-shuoshuo/         ★ 评论组件业务模块（包名 com.ruoyi.shuoshuo）
│   ├── ruoyi-demo/             接入演示站点（独立启动 :8081，签名参考实现）
│   ├── ruoyi-admin/            启动模块（static/widget 为 Widget 构建产物）
│   │   └── resources/db/migration/  ★ Flyway 增量脚本（SS_* 业务表版本化迁移）
│   ├── ruoyi-framework/        基座安全配置（放行 /api/v1/sdk|web|public|server|widget）
│   └── sql/
│       ├── ry_20260417.sql     RuoYi 基座表（含 sys_menu，人工首次执行）
│       ├── shuoshuo_ddl.sql    ★ 13 张业务表 DDL（已有库勿跑主体，按文末附录补增量）
│       └── shuoshuo_menu.sql   ★ 管理后台菜单 + 站长角色（幂等，可重复执行）
├── RuoYi-Vue3/                 管理后台前端（Vue3 + Vite + Element Plus）
│   └── src/views/shuoshuo/     数据看板 / 站点 / 评论审核 / 举报 / 敏感词 / 用户管理
├── widget/                     ★ Widget SDK 工程（原生 JS + Vite，IIFE + ESM 双格式）
├── deploy/                     ★ 部署与运维（compose / nginx / prometheus / 备份 / 压测）
├── docs/                       ★ 文档中心（索引见 docs/README.md）
└── .github/workflows/ci.yml    CI：后端单测 + Widget 测试构建 + 管理后台构建校验
```

## 快速启动（本地开发）

前置：JDK 17、Maven、MySQL 8（utf8mb4）、Redis、Node 20。逐步说明见 [docs/guide/getting-started.md](docs/guide/getting-started.md)。

1. **数据库**：MySQL 8 依次执行 `RuoYi-Vue/sql/ry_20260417.sql` → `shuoshuo_ddl.sql` → `shuoshuo_menu.sql`
   （已有旧版库：勿执行 `shuoshuo_ddl.sql` 主体；之后 `ss_*` 结构变更由 Flyway 自动执行）
2. **配置**：`RuoYi-Vue/ruoyi-admin/src/main/resources/application.yml` 中
   - Redis / MySQL 连接（application-druid.yml）
   - `shuoshuo.jwt-secret`：评论用户 JWT 密钥（**生产必须更换**）
   - `shuoshuo.github.*`：GitHub OAuth App（本地可先留默认值）
3. **后端**：`RuoYi-Vue` 下 `mvn package` 后运行 `ruoyi-admin`（默认 8080）
4. **管理后台前端**：`RuoYi-Vue3` 下 `npm install && npm run dev`
5. **Widget**：`widget/` 下 `npm install && npm run deploy`（构建并拷贝到后端 `static/widget/`）

## 站点接入（一行 script）

```html
<div class="ds-thread"></div>
<script src="http://your-server:8080/widget/widget.js"
        data-short-name="myblog" data-thread-key="post-1001" async></script>
```

站点需先在管理后台「站点管理」创建，并**配置读接口鉴权**（选错模式评论区读不出数据）：

| 模式 | 适用 | 说明 |
| --- | --- | --- |
| `origin`（默认） | 纯静态站点 | `allowed_origins` **留空即拒绝** |
| `ticket` | 有服务端、密钥不出服务端 | 服务端领票下发，SDK 自动换票 |
| `off` | 数据走自己后端 | **SDK 整体退场**，前端自研 |

详见 [docs/integration/read-auth.md](docs/integration/read-auth.md)；SSO 免二次登录见 [docs/integration/sso.md](docs/integration/sso.md)；SDK API 见 [docs/api/widget-sdk.md](docs/api/widget-sdk.md)。

## 部署与运维

完整步骤（远程 MySQL 初始化、宿主 Redis 配置、compose 启动、Nginx、监控、备份）见 **[docs/ops/deployment.md](docs/ops/deployment.md)**。要点：

- Docker 启动：`DB_HOST` / `DB_PASSWORD` / `REDIS_PASSWORD` / `SHUOSHUO_JWT_SECRET` / `TOKEN_SECRET` 经环境变量注入 compose
- Flyway：`ss_*` 表结构由 `db/migration` 版本化迁移管理，禁止改动 V1；菜单与角色走幂等的 `shuoshuo_menu.sql`
- 备份：`deploy/scripts/backup.sh`（每日 cron，保留 14 份）；**头像目录需单独备份**；恢复演练步骤见 [docs/ops/observability.md](docs/ops/observability.md)
- 监控：`/actuator/prometheus` + `deploy/prometheus/`（四条告警规则）；生产须网络层限源

## API 命名空间

| 命名空间 | 用途 | 鉴权 |
| --- | --- | --- |
| `/api/v1/sdk/**` | widget.js | 读：站点 `read_auth_mode`；写：评论用户 JWT |
| `/api/v1/web/**` | 浏览器 AJAX（账号、通知） | 评论用户 JWT |
| `/api/v1/admin/shuoshuo/**` | 管理后台 | RuoYi 原生 JWT + 权限串 |
| `/api/v1/public/**` | 注册 / 登录 / OAuth | 无（另有认证频控） |
| `/api/v1/server/**` | 站点服务端 | HMAC-SHA256 |

统一错误格式与全部错误码见 [docs/api/overview.md](docs/api/overview.md)。

## 已知限制（一期）

- GitHub OAuth 需先申请个人 OAuth App 并配置回调地址
- `comments.ip` 用于风控与审计，长期保留且不对外展示；不提供自动清理
- Widget iframe 登录态依赖 sessionStorage + refresh token 静默续期（第三方 cookie 方案已废弃，见 [ADR-0007](docs/adr/0007-no-third-party-cookie.md)）

## 版本规划

- **一期（当前）**：评论主链路、身份体系（邮箱 / GitHub / SSO）、反滥用、管理后台、Flyway + CI、Widget SDK——已完成
- **二期（规划中）**：表情包、皮肤定制、评论订阅、第三方审核 API、多 OAuth 提供方；以及一期收口项（npm 发包、日志收集、覆盖率门禁、审计查看页）

每项的范围与验收标准见 [docs/roadmap.md](docs/roadmap.md)，功能需求以 [docs/spec/overview.md](docs/spec/overview.md) §12 / §13 为准。