rizl123/seo_auditor

# SEO Scanner 全栈 Monorepo 一个高性能、容器化的即时网站 SEO 审计解决方案。本 monorepo 具有弹性的 **Go** 后端和现代化的 **Next.js** 前端，通过 **Docker** 编排，并由 **Logto OIDC** 和 **Nginx** 提供安全保障。 ## 系统架构 该项目遵循模块化的微服务方法，侧重于**整洁架构**、**安全性**和**弹性**。 - **前端**：Next.js 15 (App Router)，使用 **Server Actions** 进行安全的 API 通信，以及 **Tailwind CSS 4**。 - **后端**：Go 1.26，使用 [Huma v2](https://huma.rocks/) 实现符合 RFC 7807 规范的错误处理和 OpenAPI 3.0 规范。 - **身份验证**：集成了 **Logto (OIDC)** 和专用的 PostgreSQL 数据库。 - **审计引擎**：一个可插拔的 **Auditor** 系统，可并行运行 Meta 和性能扫描。 - **缓存**：Redis 结合定制的 **Circuit Breaker**（熔断器），即使在缓存层发生故障时也能确保 100% 的正常运行时间。 - **代理**：经过优化的 Nginx，带有大缓冲区以处理 OIDC 会话 cookie 并实现统一路由。 ## 项目结构 ``` . ├── backend/internal # Go Clean Architecture service │ ├── seo # Domain, UseCases, Infra (Auditors, Fetchers), Delivery │ └── shared/ # Resilient Caching and Redis logic ├── frontend/src # Next.js 15 Application │ ├── app # Server Actions, OIDC Routes (Login/Callback), and Pages │ ├── components # Modular UI (MainClientContainer, Navbar, Report) │ └── lib # OIDC and JWT (jose) utility logic ├── db # Postgres initialization scripts for Logto ├── nginx # Reverse Proxy with OIDC buffer optimizations └── .github/workflows # CI/CD (Go race detector, Biome linting, Docker builds) ``` ## 快速开始（生产模式） 要在生产模式下启动整个技术栈（前端、后端、Redis、Postgres、Logto、Nginx）： ``` docker compose --profile prod up --build ``` - **Web UI**: [http://seo.localhost](http://seo.localhost) - **认证控制台**: [http://admin.seo.localhost](http://admin.seo.localhost) - **API 文档**: [http://seo.localhost/swagger/](http://seo.localhost/swagger/) ## 开发工作流 本 monorepo 使用 **Docker Profiles** 来管理环境，避免端口冲突。 ### 1. 后端开发 (`back_dev`) 包含用于代码热重载的 **Air**。 ``` docker compose --profile back_dev up ``` ### 2. 前端开发 (`front_dev`) 包含 **Next.js HMR**。 ``` docker compose --profile front_dev up ``` ## 配置 ### 环境变量 应用程序使用多个环境变量进行配置。以下是 `.env`、`.env.backend` 和 `.env.frontend.local` 文件中变量的详细说明。 #### 1. 数据库与身份验证 (`.env`) | 变量 | 描述 | 默认值 / 示例 | | :--- | :--- | :--- | | `DB_ROOT_PASSWORD` | 数据库实例的 root 密码 | *必填* | | `AUTH_DB_PASSWORD` | Auth 服务的数据库用户密码 | *必填* | #### 2. 后端与缓存 (`.env.backend`) | 变量 | 描述 | 默认值 | | :--- | :--- | :--- | | `REDIS_ADDR` | Redis 连接字符串 | `localhost:6379` | | `APP_PORT` | 内部后端端口 | `8080` | | `ALLOWED_ORIGINS` | CORS 白名单 (以逗号分隔) | `*` | | `CACHE_TTL` | 报告在缓存中的保留时间 | `1h` | | `CACHE_BREAK_DURATION` | 缓存刷新之间的冷却时间 | `1m` | #### 3. 前端与 OIDC (`.env.frontend.local`) | 变量 | 描述 | 默认值 / 示例 | | :--- | :--- | :--- | | `OIDC_ID` | OpenID Connect Client ID | *必填* | | `OIDC_SECRET` | OpenID Connect Client Secret | *必填* | ## 🔒 安全性与弹性 - **OIDC 身份验证**：通过 Logto 进行安全的会话管理；前端使用 `jose` 和 `openid-client` 实现 JWT 验证。 - **SSRF 防护**：Go 语言的 `Fetcher` 使用带有预拨号 DNS 解析的自定义 `http.Client`，以阻止 **RFC 1918** 私有网段和环回地址。 - **流式解析器**：使用原生的 `html.Tokenizer` 来减少内存占用，并防止通过大量 HTML 负载发起的 DoS 攻击（限制为 512KB）。 - **熔断器**：如果 Redis 无法连接，`CachedAuditor` 将进入“开启”状态，绕过缓存以维持 API 的可用性。 - **优雅关机**：后端会捕获 `SIGTERM/SIGINT` 信号，以关闭 Redis 连接并完成活跃的请求。 ## 🧪 测试与质量控制 该项目采用强类型，并由自动化测试套件提供保障。 ### 后端 包含竞争检测和 `miniredis` 集成测试。 ``` cd backend && go test -v -race ./internal/... ``` ### 前端 使用 **Biome** 进行极速的代码检查和格式化。 ``` cd frontend && npm run lint:check && npm run format:check ``` ### CI/CD 每次向 `main` 分支推送时都会触发 GitHub Actions： 1. **后端 CI**：使用 `-race` 检测器运行测试。 2. **前端 CI**：验证代码检查和格式化。 3. **Docker CI**：验证所有 profile 是否成功构建。 ## 📖 API 文档 API 是自文档化的。Huma v2 动态生成 OpenAPI 3.0 规范。 - **JSON 规范**：`http://seo.localhost/api/openapi` - **交互式 UI**：`http://seo.localhost/swagger/` ## 📝 许可证 本项目基于 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。 版权所有 (c) 2026 Rizl

标签：App Router, CISA项目, Docker容器化, GitHub Actions, Go语言, Huma v2, JWT, Logto, Next.js 15, Nginx反向代理, OIDC认证, OpenAPI, PostgreSQL数据库, Redis缓存, SEO审计, SEO扫描器, Server Actions, TypeScript, Web安全, 后端开发, 安全插件, 干净架构, 弹性设计, 微服务架构, 性能分析, 搜索引擎查询, 日志审计, 测试用例, 熔断器, 程序破解, 网站优化, 网站检测, 网络资产识别, 自动笔记, 蓝队分析, 请求拦截