Xiuno BBS开源程序交流论坛
Xiuno BBS 4.2.0 基于 Xiuno BBS 4.0.4 开发的现代化套件
jinqike1026
发布于 2小时前
# Atlas Xiuno Discourse 现代化套件 (v4.2.0-atlas)
作者：金小颖 · https://52jiny.com/
本次新增的现代化能力（均为**附加式**，不破坏 Xiuno 原有逻辑；未做配置时行为与原版一致）。
---
## 1. RESTful API（`/api/`）
复用 Xiuno 现有 token 机制，提供规范化 JSON 资源接口、鉴权与限流。
### 调用方式
- 无重写：`/api/index.php?_p=v1/threads&fid=1&page=1`
- 美化路径（已附带 `api/.htaccess`）：`/api/v1/threads?fid=1&page=1`
### 鉴权
- 登录获取 token：`POST /api/v1/auth/login`，参数 `email`(或 `username`) + `password`
- 后续请求携带：HTTP 头 `Authorization: Bearer <token>`，或 `?token=<token>`
- token 由原生 `user_token_gen()` 生成，与站点登录态互通。
### 限流
- 默认 **120 次/分钟**（按 uid 或 IP 滑动窗口，文件计数于 `tmp/atlas_api/`）。
- 在 `conf/conf.php` 设 `'atlas_api_rate' => N` 调整；`0` 关闭。
- 超限返回 `429` + `Retry-After`、`X-RateLimit-*` 头。
### 端点（v1）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `v1/ping` | 健康检查 |
| POST | `v1/auth/login` | 登录，返回 token + 用户 |
| GET | `v1/me` | 当前用户（需鉴权） |
| GET | `v1/forums` | 可见版块列表 |
| GET | `v1/forums/{fid}/threads` | 版块主题列表（分页） |
| GET | `v1/threads?fid=&page=` | 主题列表（不传 fid 跨可见版块） |
| GET | `v1/threads/{tid}` | 主题详情 + 帖子 |
| GET | `v1/threads/{tid}/posts` | 主题帖子列表 |
| GET | `v1/users/{uid}` | 用户公开资料 |
### 响应信封
```json
{ "code": 0, "message": "ok", "data": {...}, "meta": { "page": 1, "total": 42, "totalpage": 3 } }
```
- `code=0` 成功；非 0 为错误码，HTTP 状态同步（401/403/404/405/429）。
- 输出仅白名单字段，**不泄露** email/password/salt。
- 列表已通过 `thread_list_access_filter` / `post_list_access_filter` 做权限过滤。
---
## 2. 安全加固（`model/atlas_security.func.php`）
已注册进 `model.inc.php`，全站可用。
- **密码哈希升级**：`atlas_password_verify()` 同时支持 `password_hash`(bcrypt/argon2) 与旧 `md5+salt`；登录验证已接入，**老用户无感**。开启完整 `password_hash` 见下方迁移步骤。
- **透明 rehash**：开启后，旧用户登录成功时自动升级为 `password_hash`（失败不影响登录）。
- **CSRF（v4.1.5 增强）**：
- `atlas_csrf_guard()` 同源守卫已接入 `index.inc.php` 路由中枢，**自动对所有 POST 写操作生效**（校验 Origin/Referer 同源；跨站请求返回 403）。采用“有头则验、无头放行”策略，不破坏同源浏览器表单与 CLI/服务器回调。API（走 `SKIP_ROUTE`）不受影响。
- 开关：`conf['atlas_csrf_on']`（默认 1，0=关）；白名单：`conf['atlas_csrf_skip_routes']`（逗号分隔，供支付/第三方回调路由使用）。
- `atlas_csrf_token()` / `atlas_csrf_check()`（基于 `xn_safe_key()`）仍保留，可用于显式 token 校验。
- **上传加固（v4.1.5）**：新增 `upload/.htaccess`，在上传目录及其子目录**禁止执行 PHP/脚本（防 webshell）**。原生逻辑另将非白名单扩展名加 `_` 前缀中和。Nginx 需手动配置：`location ^~ /upload/ { location ~* \.(php|phtml|phar|cgi|pl|py|jsp|asp)$ { deny all; } }`。
- **SSRF 防护**：`atlas_ssrf_safe_url($url)` 拦截内网/回环/保留地址；`atlas_safe_http_get()` 为带防护的远程抓取封装。
- **输出转义**：API 输出走白名单 + `xn_json_encode`；模板沿用 Xiuno `htmlspecialchars`/`param()` 转义链。
### 启用 password_hash（v4.1.5：一键脚本，推荐）
方法 A（推荐）：以**创始人账号登录**后访问 `你的域名/install/atlas_upgrade.php`，点“立即升级”——脚本会自动加宽 `password`/`salt` 至 255 并写入 `atlas_pwhash` 开关（存于 kv）。完成后请删除该文件。
方法 B（手动）：执行 `install/atlas_security_upgrade.sql`（把表前缀 `xn_` 改成实际前缀）→ 在 `conf/conf.php` 增加 `'atlas_pwhash' => 1,`。
两者任选其一；此后新注册用 `password_hash`，老用户登录成功时自动透明迁移。
> 未执行时系统保持原 `md5+salt`，行为不变，不影响现网。
---
## 3. 关于「全站 BS5.3 + 彻底替换 jQuery/BS4」与「发帖/回复 HTMX 无刷新」
诚实说明现状与取舍：
- 已完成：全站 Discourse 视觉皮肤（`discourse-skin.css`，含后台/安装页）、新首页（HTMX 加载更多）、**全站引入 HTMX**（渐进式增强基础设施已就位）。
- **暂缓**：把 `xiuno.js / bbs.js / form.js / async.js` 等**深度依赖 jQuery 的核心交互**（登录、发帖、上传、下拉、异步表单）盲目替换为 BS5.3 原生 + HTMX。原因：本环境无法运行 PHP/浏览器联调，盲改极易弄坏发帖与上传等关键路径。
- 建议的安全推进路径：以 HTMX 为基础，**逐页**为帖子详情/发帖/回复表单加 `hx-post`/`hx-target` 并提供 partial 响应端点（首页已示范），在可联调环境下分步替换，每步回归验证。本套件的 REST API 也可直接支撑前端无刷新交互。
## 4. v4.2.0-atlas (Beta（测试）版，尚未经过集成测试)
- **前端切换开关 `atlas_frontend`**（位于 `conf.default.php`）：设为 `0` 时走老版本 jQuery3 + Bootstrap4 方案（默认配置，方便安全回滚）；设为 `1` 时则启用全新的 Bootstrap 5.3 + HTMX 方案，并搭配原生的 `atlas-runtime.js`。
- **新增文件**：加入了 `view/js/atlas-runtime.js`（用来替代原来的 jQuery、xiuno.js 和 form.js），以及 `view/css/atlas-bs5-bridge.css`（作为 BS4 到 BS5 的样式兼容垫片）。
- **HTMX 无刷新回帖**：在 `thread.htm` 和 `route/post.php` 中完成了对接，当检测到 `HX_REQUEST` 时，会直接返回渲染好的楼层 HTML。
- **属性迁移**：在 `view/htm` 和 `admin/view/htm` 目录下，全面补充并迁移了 `data-bs-*` 相关属性。
相关帖子
最新回复 (0)
全部楼主
|
3 主题数 |
59 帖子数 |
扫码访问