# NaxResource
**Repository Path**: b_bang/nax-resource
## Basic Information
- **Project Name**: NaxResource
- **Description**: 🎉 NaxResource · 资源聚合站 · 后端 Webman 2.x + PHP 8.3 + Eloquent + JWT · 前端 Vue 3 + TypeScript + Vite + Element Plus + Pinia
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# NaxResource
**AI 驱动的资源与工具导航门户**
前台 Nuxt 3 探索发现 · AI 助理对话 + AI 自动收录 · 后台 Vue 3 内容管理 + RBAC
后端 Webman 2.x + PHP 8.4 + 多 Agent 编排 · 全栈 TypeScript + PHP · MIT
[](LICENSE)
[](https://www.php.net)
[](https://www.workerman.net/webman)
[](https://nuxt.com)
[](https://vuejs.org)
[](https://vitejs.dev)
---
## 简介
**NaxResource** 是一个 AI 驱动的资源与工具导航门户。面向访客的前台聚合、展示与检索优质 **资源 / 工具 / 合集 / 标签**,内置 **AI 助理对话** 与 **AI 自动收录**;配套后台负责内容运营与权限管理。全栈 TypeScript + PHP,遵循严格分层(CQRS-lite),开箱即用。
三层构成:
- 🌐 **前台门户**(`web-ui/`,Nuxt 3 SSR)— 多维导航 + 搜索发现 + 用户互动(收藏 / 点赞 / 订阅),Three.js 沉浸式粒子背景 + 分级性能降载,SSR 友好 SEO。
- 🤖 **AI 能力**(`app/common/ai/`)— 基于 neuron-ai 的多 Agent 编排:后台对话助理调度收录专家自动抓取元数据、联网搜索、查重、分类、入库;前台纯只读站内 RAG 问答助理。
- 🛠️ **管理后台**(`admin-ui/`,Vue 3 + Element Plus)— 内容管理 + AI 配置 + 完整 RBAC / JWT + 异步日志队列,构建于自研 Webman 分层脚手架之上。
---
## 功能特性
### 🌐 前台门户(Nuxt 3 SSR)
- **多维导航** — 资源 / 工具 / 合集 / 标签四条主线,发现页聚合置顶 / 热门 / 最新。
- **搜索发现** — 站内搜索 + 建议词 + 热门关键词 + 按标签 / 分类检索。
- **用户互动** — 收藏 / 点赞 / 订阅 / 评论;未登录本地收藏(localStorage),登录后云端同步。
- **AI 对话** — 全屏对话页 + 右下角悬浮助手,SSE 真流式(text / reasoning / tool_call 分块),可选联网与思考开关,会话线程与历史。
- **完整账号体系** — 注册 / 登录 / 找回 / 邮箱验证 / 第三方 OAuth 绑定 / 邀请码。
- **用户中心** — 我的收藏 / 点赞 / 订阅 / AI 历史 / 站内通知 / 邀请好友。
- **沉浸式视觉** — Three.js 粒子网格背景(空间哈希优化 + 自动降级)、anime.js 动效、深色主题(品牌色后台可配)、SEO / sitemap / robots / RSS / PWA manifest。
### 🤖 AI 多 Agent 编排
- **对话 + 调度主 Agent**(AssistantAgent)— 后台管理员的只读调研助理,收录须经明确确认后委托专家。
- **自动收录专家**(IngestAgent)— 接受 URL / 名称 / 自然语言,自主抓取 → 联网搜索 → 查重 → 查分类 → 判定资源/工具 → 入库存草稿(待人工审核),独立线程执行并回传轨迹报告。
- **前台只读助理**(UserAssistantAgent)— 仅从站内已收录内容检索作答与推荐,无写权限。
- **工具链** — 8 个工具:抓元数据(SSRF 防护)/ 查重 / 列分类 / 存资源 / 存工具 / 搜资源 / 搜工具 / 搜合集;基于 neuron-ai 3.15 + DeepSeek,可选 Tavily 联网。
### 📦 内容管理(后台)
- **资源 / 工具 / 合集 / 分类 / 标签 / 评论审核 / RSS 订阅源** 全套 CRUD + 批量操作。
- **草稿审核流** — AI 收录一律存草稿,人工审核后发布。
- **NaxTable** schema 化表格 — 新页只写 columns 定义,自动出分页 / 排序 / 操作列 / 批量。
### 🔐 系统与安全
- **完整 RBAC** — Admin / Role / Menu / Operation / API 五表关联,超管短路 + 普通管理员单 SQL JOIN 校验。
- **JWT + Redis 黑名单** — 登出即失效,验证码 GETDEL 原子防重放。
- **异步日志队列** — 操作日志走 Redis 队列 + 独立 worker 批量落库,Redis 不可达自动降级同步。
- **定时任务引擎** — class / command(白名单防 RCE)/ url(白名单防 SSRF)三型,启停 + 表达式校验 + 统计。
- **基础设施** — 配置中心 / 字典 / 文件与图库(SHA1 去重 + GD 缩略图)/ 邮件(SMTP + 模板 + 日志)/ 站内信精确推送 / 行政区划(GB-T 2260)/ 用户与 AI 配额管理。
---
## 技术栈
**后端**
| 层 | 技术 |
|---|---|
| Runtime | PHP 8.4+ · Workerman 5 · Webman 2.x |
| ORM / 校验 | Eloquent(webman/database)· webman/validation |
| Cache / Queue | Redis(phpredis 优先,predis 兜底) |
| AI | neuron-ai 3.15 · DeepSeek · Tavily(可选联网) |
| Auth / Mail / Cron | firebase/php-jwt · PHPMailer · workerman/crontab |
**前台门户**(`web-ui/`)
| 层 | 技术 |
|---|---|
| Framework | Nuxt 3 SSR · Vue 3 · TypeScript |
| 样式 / 组件 | Tailwind CSS + 自研组件 |
| 视觉 | Three.js 粒子背景 · anime.js 动效 |
| 内容 | markdown-it + highlight.js + DOMPurify |
**管理后台**(`admin-ui/`)
| 层 | 技术 |
|---|---|
| Framework | Vue 3.5 · TypeScript · Vite 7 |
| UI / State | Element Plus · Pinia · Tailwind(Art Design Pro 基底) |
| Router / HTTP | Vue Router(动态菜单)· Axios(JWT 自动注入) |
---
## 项目结构
```
.
├── app/
│ ├── adminApi/ # 后台 API(七层分层,按业务域分组)
│ ├── api/ # 前台 API(portal / user / ai / notify)
│ ├── common/ai/ # 多 Agent 编排(Agent + orchestration + tool)
│ ├── model/ # Eloquent Model
│ └── process/ # 常驻 worker(Cron / 日志消费)
├── web-ui/ # 前台门户(Nuxt 3 SSR)
├── admin-ui/ # 管理后台(Vue 3 + Art Design Pro)
├── database/ # schema.sql + init / seed / sync 脚本
├── config/ support/ extend/ # webman 配置与分层基类
└── CLAUDE.md # 项目规范(强制项)
```
---
## 快速开始
### 环境要求
- PHP **8.4+** · MySQL 5.7+ / MariaDB 10.4+ · Redis 5.0+ · Composer 2.x
- (前端可选)Node **20+** · pnpm 9+
### 1. 后端
```bash
git clone https://gitee.com/kz_y/nax-resource.git
cd nax-resource
composer install
cp .env.example .env # 填 DB / Redis / JWT_SECRET / DeepSeek key
php database/check.php # 自检 MySQL / Redis 可连
php database/init.php # 建库 + 建表 + 灌种子
```
> `JWT_SECRET` 生成:`php -r "echo bin2hex(random_bytes(32));"`
### 2. 启动 + 同步权限
```bash
php windows.php # 启动(Linux/macOS: php start.php start),监听 :8787
php database/sync_apis.php # 扫路由入库 + 自动绑超管 RBAC(每次新增路由后重跑)
```
默认后台账号 **`admin / admin123`**(生产务必改)。探活:`curl http://127.0.0.1:8787/adminApi/captcha`。
### 3. 前端(可选)
```bash
# 管理后台
cd admin-ui && pnpm install && pnpm dev # http://localhost:3006
# 前台门户
cd web-ui && pnpm install && pnpm dev # http://localhost:3000
```
前端默认请求后端 `http://127.0.0.1:8787`,如需改见各自 `.env`。
---
## 生产部署
### 1. 环境变量
```bash
cp .env.example .env
```
必填三项(否则启动即报错或全站资源 URL 指向 127.0.0.1 而 404):
| 变量 | 说明 |
|---|---|
| `APP_URL` | 后端对外根地址(拼头像 / 封面 / 文件 URL)。**非本机部署必须改真实域名**。 |
| `APP_WEB_URL` | 前台门户根地址(邮件里的激活 / 重置密码链接指向它)。 |
| `JWT_SECRET` | **≥32 位**随机串,留空签发 / 校验直接抛错:`php -r "echo bin2hex(random_bytes(32));"` |
### 2. 建库 + 灌种子(顺序不能乱)
SQL 用 `apply_sql.php` 执行(绕开 cli 编码坑),脚本用 `php`:
```bash
php database/check.php # 先自检 MySQL / Redis 可连
php database/apply_sql.php database/schema.sql # 1. 建表(全部表结构)
php database/apply_sql.php database/seed_full.sql # 2. 种子:RBAC / 菜单 / 配置 / 字典 + 默认 DeepSeek 模型行
php database/apply_sql.php database/cron_seed.sql # 3. 注册内置定时任务
php database/sync_apis.php # 4. 扫路由入库 + 自动绑超管 RBAC(每次新增路由后重跑)
```
默认后台账号 **`admin / admin123`**(生产务必改)。
### 3. 首次启动后配置(后台内,不走 .env)
后端起来后登录后台补两处运行期配置:
- **AI 配置** — 给默认 DeepSeek 模型填 `API Key`(种子已建好该行,key 留空);未配则 AI 对话 / 收录不可用。
- **邮件配置** — 填 SMTP;未配则注册走自动激活降级、找回密码不发信。
### 4. 前台门户 web-ui(Nuxt 3 SSR)
```bash
cd web-ui
export NUXT_PUBLIC_API_BASE=https://api.your-domain.com # 后端地址,默认 http://127.0.0.1:8787
pnpm install && pnpm build # 产物 .output/
HOST=0.0.0.0 PORT=3000 node .output/server/index.mjs # 常驻监听 :3000(建议 pm2 / systemd 守护)
```
由 nginx 反代::3000 收 `/` 流量,`/api`、`/adminApi` 转发给 webman(样板见 `deploy/nginx.conf`)。
### 5. 管理后台 admin-ui(静态 SPA)
**构建前**先改后端地址:`admin-ui/.env.production` 的 `VITE_API_URL` 改成生产 `/adminApi` 地址,再:
```bash
cd admin-ui && pnpm install && pnpm build # 产物 admin-ui/dist,用 nginx / 任意静态服务器托管
```
### 6. 备份
```bash
bash deploy/backup.sh /data/naxbak # mysqldump + public/uploads 打包,带时间戳
```
### Docker(可选)
`docker-compose.yml` 提供 MySQL + Redis + Webman(app)+ Nginx 一栈:
```bash
docker compose up -d --build # JWT_SECRET 未设会 fail-loud 拒绝启动
docker compose exec app php database/apply_sql.php database/schema.sql # 灌库(再 seed_full / cron_seed / sync_apis,顺序同上)
```
> 前台 **web-ui SSR 不在栈内**(SSR 与浏览器共用同一 `apiBase`,容器内无法两端同时可达),需在宿主机 `:3000` 常驻(见第 4 步),nginx 经 `host.docker.internal` 反代。
---
## License
[MIT](LICENSE) © 2026 [kzy](https://gitee.com/kz_y)