(C) 2024-now XDSEC Developers
下面是仓库的主要目录和文件的简要说明,帮助新来维护者快速理解项目布局:
.
├─ biome.json # Biome / lint / formatter 配置
├─ Cargo.toml # Workspace / Rust 根配置
├─ README.md # 本文件
├─ crates/
│ ├─ database/ # 数据库相关 crate(实体、查询、迁移逻辑)
│ │ ├─ Cargo.toml
│ │ └─ src/
│ │ ├─ lib.rs
│ │ └─ entities/ # ORM 实体(user, report, config 等)
│ └─ server/ # 后端服务(axum + handlers + middleware)
│ ├─ Cargo.toml
│ └─ src/
│ ├─ main.rs
│ ├─ lib.rs
│ ├─ routes/ # 所有 HTTP 路由定义
│ └─ middleware/ # 中间件(auth, data 等)
├─ docs/ # 文档(非必需,但用于项目说明或设计文档)
├─ web/ # 前端(SolidJS + Vite)
│ ├─ package.json
│ ├─ vite.config.mts
│ └─ src/
│ ├─ index.tsx # 前端入口
│ ├─ lib/ # 前端库代码(api、i18n、storage、widgets 等)
│ │ ├─ api/
│ │ ├─ i18n/
│ │ └─ widgets/
│ └─ routes/ # 前端页面路由
└─ public/ # 前端静态资源(manifest 等)
简要说明:
crates/database:包含数据模型和数据库访问函数(sea-orm / sqlx)。crates/server:后端 HTTP 服务实现,路由在routes/,鉴权与请求预处理在middleware/。web:前端单页应用,使用 Vite 构建。常见修改点包括src/lib/api(与后端交互的封装)和src/routes(页面逻辑)。
项目使用后端和前端的环境变量来控制运行行为。下面给出维护者和贡献者的简要说明,包括应该设置哪些变量、示例以及这些变量会影响的功能。
-
DATABASE_URL(必需)- 说明:数据库连接字符串。
- 示例(MySQL):
mysql://root:password@127.0.0.1/wr
-
WR_HOST(必需)- 说明:服务绑定的主机地址
-
WR_PORT(必需)- 说明:服务监听的端口
-
WR_PUBLIC_URL(可选)- 说明:后端用于生成站点级绝对链接(例如 RSS feed 中的 self 链接或在服务端构造的 URL)的基准公开地址。该值应设置为你的站点对外可访问的完整根 URL(例如
https://weekly.example.com)。 - 默认:如果未设置,服务在代码中回退到
http://localhost(见crates/server/src/routes/mod.rs中的处理)。 - 注意:请在生产环境中设置该值以确保 feed 中的链接与真实域名一致;设置时通常不需要尾部斜杠(代码会安全地去除尾斜杠)。
- 说明:后端用于生成站点级绝对链接(例如 RSS feed 中的 self 链接或在服务端构造的 URL)的基准公开地址。该值应设置为你的站点对外可访问的完整根 URL(例如
在启动后端和前端前,可在当前 PowerShell 会话中临时设置:
$env:WR_HOST = '127.0.0.1' $env:WR_PORT = '8080' $env:DATABASE_URL = 'mysql://root:root@localhost/wr' $env:WR_STATIC = 'C:\Users\you\path\to\weekly_report\web' $env:RUST_LOG = 'info'
然后在不同终端分别启动后端与前端:
# 启动后端 cd C:\Users\you\path\to\weekly_report cargo run --bin wr-server # 启动前端开发服务器 cd C:\Users\you\path\to\weekly_report\web npm install npm run dev