Files
novalon-website/README.md
T
2026-04-01 23:27:25 +08:00

716 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Novalon Website
四川睿新致远科技有限公司官方网站 - 企业数字化转型服务商
## 项目概述
本项目是四川睿新致远科技有限公司的企业官网,采用 Next.js 16 + React 19 + TypeScript 技术栈构建,提供现代化的企业展示、产品服务介绍、案例展示、新闻动态和在线咨询等功能。
### 核心功能
- **首页展示** - Hero 区域、核心业务、产品服务、成功案例、关于我们、新闻动态
- **服务详情** - 软件开发、云服务、数据分析、信息安全等服务详细介绍
- **产品展示** - 产品列表和详情页面
- **案例展示** - 成功案例列表和详情
- **新闻动态** - 公司新闻、产品发布、合作动态、行业资讯
- **在线咨询** - 联系表单、公司信息展示
- **响应式设计** - 完美适配桌面端、平板和移动设备
- **SEO 优化** - 结构化数据、元信息优化
- **CMS管理后台** - 内容管理、用户管理、配置中心、审计日志
## 技术栈
| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Next.js | 16.1.6 |
| UI 库 | React | 19.2.3 |
| 语言 | TypeScript | 5.x |
| 样式 | Tailwind CSS | 4.x |
| 组件库 | shadcn/ui (Radix UI) | - |
| 动画 | Framer Motion | 12.x |
| 图标 | Lucide React | 0.563.0 |
| 邮件服务 | Resend | 6.9.2 |
| 数据验证 | Zod | 4.3.6 |
| 图表 | @antv/g2 | 5.4.8 |
| 3D 效果 | Three.js | 0.183.1 |
| 数据库 | SQLite | - |
| ORM | Drizzle ORM | - |
| 认证 | NextAuth.js | 5.x beta |
| 富文本编辑 | Tiptap | - |
## 快速开始
### 环境要求
- Node.js 18+
- npm / yarn / pnpm / bun
### 安装依赖
```bash
npm install
```
### 环境变量配置
复制环境变量示例文件:
```bash
cp .env.example .env.local
```
配置必要的环境变量:
```env
# 邮件服务
RESEND_API_KEY=your_resend_api_key
COMPANY_EMAIL=contact@novalon.cn
# 数据库
DATABASE_URL=./data/novalon.db
# NextAuth.js
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000
# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760
# 管理员账号(首次运行时创建)
ADMIN_EMAIL=contact@novalon.cn
ADMIN_PASSWORD=your_secure_password
```
### 开发模式
```bash
npm run dev
```
访问 http://localhost:3000
### 构建生产版本
```bash
npm run build
```
输出目录: `dist/`
### 启动生产服务器
```bash
npm start
```
## 项目结构
```
novalon-website/
├── src/ # 源代码
│ ├── app/ # Next.js App Router
│ │ ├── (marketing)/ # 营销页面路由组
│ │ │ ├── page.tsx # 首页
│ │ │ ├── about/ # 关于我们
│ │ │ ├── cases/ # 成功案例
│ │ │ ├── contact/ # 联系我们
│ │ │ ├── news/ # 新闻动态
│ │ │ ├── products/ # 产品服务
│ │ │ ├── services/ # 核心业务
│ │ │ └── solutions/ # 解决方案
│ │ ├── admin/ # 管理后台
│ │ │ ├── page.tsx # 仪表盘
│ │ │ ├── login/ # 登录页面
│ │ │ ├── content/ # 内容管理
│ │ │ ├── users/ # 用户管理
│ │ │ ├── settings/ # 配置中心
│ │ │ └── logs/ # 审计日志
│ │ ├── api/ # API 路由
│ │ │ ├── auth/ # 认证 API
│ │ │ ├── contact/ # 联系表单 API
│ │ │ └── admin/ # 管理 API
│ │ │ ├── content/ # 内容管理
│ │ │ ├── users/ # 用户管理
│ │ │ ├── config/ # 配置管理
│ │ │ ├── upload/ # 文件上传
│ │ │ └── logs/ # 审计日志
│ │ ├── layout.tsx # 根布局
│ │ ├── error.tsx # 错误页面
│ │ └── not-found.tsx # 404 页面
│ ├── components/ # React 组件
│ │ ├── ui/ # 基础 UI 组件
│ │ ├── layout/ # 布局组件
│ │ ├── sections/ # 页面区块组件
│ │ ├── effects/ # 视觉效果组件
│ │ ├── seo/ # SEO 组件
│ │ ├── analytics/ # 分析组件
│ │ └── admin/ # 管理后台组件
│ ├── lib/ # 工具函数
│ │ ├── api/ # API 服务
│ │ ├── auth/ # 认证相关
│ │ ├── db.ts # 数据库连接
│ │ ├── audit.ts # 审计日志
│ │ └── upload.ts # 文件上传
│ ├── db/ # 数据库相关
│ │ ├── schema.ts # 数据库 Schema
│ │ ├── seed.ts # 种子数据
│ │ └── migrations/ # 迁移文件
│ ├── hooks/ # 自定义 Hooks
│ └── contexts/ # React Context
├── e2e/ # E2E 测试(统一测试框架)
│ ├── src/
│ │ ├── tests/ # 测试用例
│ │ │ ├── smoke/ # 冒烟测试
│ │ │ ├── regression/ # 回归测试
│ │ │ ├── api/ # API 测试
│ │ │ ├── accessibility/ # 可访问性测试
│ │ │ ├── performance/ # 性能测试
│ │ │ ├── security/ # 安全测试
│ │ │ └── visual/ # 视觉回归测试
│ │ ├── pages/ # Page Object
│ │ ├── fixtures/ # 测试 Fixtures
│ │ └── config/ # 测试配置
│ ├── playwright.config.ts
│ └── MIGRATION.md # 测试框架迁移说明
├── docs/ # 项目文档
│ ├── architecture/ # 架构文档
│ ├── development/ # 开发文档
│ ├── deployment/ # 部署文档
│ ├── testing/ # 测试文档
│ ├── api/ # API 文档
│ ├── guides/ # 使用指南
│ ├── STRUCTURE_PLAN.md # 目录结构规划
│ └── OPTIMIZATION_REPORT.md # 优化报告
├── scripts/ # 脚本文件
│ ├── deployment/ # 部署脚本
│ ├── monitoring/ # 监控脚本
│ ├── testing/ # 测试脚本
│ ├── maintenance/ # 维护脚本
│ └── utils/ # 工具脚本
├── config/ # 配置文件
│ ├── ci/ # CI/CD 配置
│ ├── lint/ # 代码检查配置
│ └── test/ # 测试配置
├── reports/ # 测试报告
│ ├── e2e/ # E2E 测试报告
│ ├── performance/ # 性能测试报告
│ └── coverage/ # 代码覆盖率报告
├── public/ # 静态资源
├── uploads/ # 上传文件存储
├── data/ # SQLite 数据库文件
└── dist/ # 构建输出
```
### 项目优化说明
本项目已于 2026-03-24 完成全面的工程化与规范化优化,包括:
1. **测试体系整合** - 统一为 Playwright TypeScript 测试框架
2. **目录结构规范化** - 建立清晰的目录结构,符合 Next.js 最佳实践
3. **配置文件优化** - 合并重复配置,统一配置管理
4. **文档体系完善** - 建立完整的文档体系和导航
5. **代码质量提升** - 修复所有类型错误,确保构建成功
详细信息请查看 [优化报告](docs/OPTIMIZATION_REPORT.md)
## 页面路由
| 路由 | 描述 |
|------|------|
| `/` | 首页 |
| `/about` | 关于我们 |
| `/services` | 核心业务列表 |
| `/services/[id]` | 业务详情 |
| `/products` | 产品服务列表 |
| `/products/[id]` | 产品详情 |
| `/cases` | 成功案例列表 |
| `/cases/[id]` | 案例详情 |
| `/news` | 新闻动态列表 |
| `/news/[slug]` | 新闻详情 |
| `/contact` | 联系我们 |
| `/privacy` | 隐私政策 |
| `/terms` | 服务条款 |
| `/admin` | 管理后台仪表盘 |
| `/admin/login` | 管理员登录 |
| `/admin/content` | 内容管理 |
| `/admin/content/[id]` | 内容编辑 |
| `/admin/users` | 用户管理 |
| `/admin/settings` | 配置中心 |
| `/admin/logs` | 审计日志 |
## NPM 脚本
| 命令 | 描述 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm start` | 启动生产服务器 |
| `npm run lint` | 运行 ESLint 检查 |
| `npm run test` | 运行 E2E 测试 |
| `npm run test:smoke` | 运行冒烟测试 |
| `npm run check:contrast` | 检查颜色对比度 |
| `npm run check:headings` | 检查标题层级 |
| `npm run db:generate` | 生成数据库迁移文件 |
| `npm run db:migrate` | 执行数据库迁移 |
| `npm run db:seed` | 填充数据库种子数据 |
| `npm run db:studio` | 启动 Drizzle Studio |
## 代码质量门禁
项目配置了自动化质量门禁,确保代码提交前通过所有质量检查:
- **ESLint**: 代码风格检查
- **commitlint**: 提交信息规范
- **Jest**: 代码覆盖率检查
详细信息请查看 [质量门禁文档](docs/development/quality-gates.md)。
### 提交规范
使用Conventional Commits规范:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**提交类型**:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具相关
## 测试
项目使用 Playwright 进行 E2E 测试,测试框架位于 `e2e/` 目录。
### 测试类型
- **冒烟测试** - 基础功能验证
- **回归测试** - 功能完整性验证
- **API测试** - 后端API接口测试
- **性能测试** - Core Web Vitals
- **响应式测试** - 多设备适配
- **可访问性测试** - WCAG 合规
- **安全测试** - XSS、CSRF 防护
- **视觉回归测试** - UI 一致性
### 运行测试
```bash
cd e2e
npm install
npm run test
```
## 管理后台
### 功能模块
#### 内容管理
- 支持新闻、产品、服务、案例四种内容类型
- 富文本编辑器(支持图片上传)
- 内容版本管理
- 草稿/发布/归档状态管理
#### 用户管理
- 用户创建、编辑、删除
- 角色权限控制(管理员、编辑、查看者)
- 密码加密存储
#### 配置中心
- 网站基本信息配置
- SEO配置
- 联系信息配置
- 分类管理
#### 审计日志
- 操作记录追踪
- 按操作类型、资源类型筛选
- 分页查询
### 权限说明
| 角色 | 内容管理 | 用户管理 | 配置管理 | 审计日志 |
|------|---------|---------|---------|---------|
| admin | 全部权限 | 全部权限 | 全部权限 | 查看权限 |
| editor | 创建、编辑、发布 | 无权限 | 查看权限 | 查看权限 |
| viewer | 查看权限 | 无权限 | 查看权限 | 查看权限 |
### API 接口
#### 认证接口
- `POST /api/auth/signin` - 登录
- `POST /api/auth/signout` - 登出
- `GET /api/auth/session` - 获取会话信息
#### 内容管理接口
- `GET /api/admin/content` - 获取内容列表
- `POST /api/admin/content` - 创建内容
- `GET /api/admin/content/[id]` - 获取内容详情
- `PUT /api/admin/content/[id]` - 更新内容
- `DELETE /api/admin/content/[id]` - 删除内容
#### 用户管理接口
- `GET /api/admin/users` - 获取用户列表
- `POST /api/admin/users` - 创建用户
- `GET /api/admin/users/[id]` - 获取用户详情
- `PUT /api/admin/users/[id]` - 更新用户
- `DELETE /api/admin/users/[id]` - 删除用户
#### 配置管理接口
- `GET /api/admin/config` - 获取配置列表
- `POST /api/admin/config` - 更新配置
#### 文件上传接口
- `POST /api/admin/upload` - 上传文件
- `DELETE /api/admin/upload` - 删除文件
#### 审计日志接口
- `GET /api/admin/logs` - 获取审计日志列表
## CI/CD
项目使用 Woodpecker CI 进行持续集成,配置文件为 `.woodpecker/` 目录。
CI 流水线包括:
- **CI 工作流** (`.woodpecker/ci.yml`) - 代码检查、测试、构建
- **部署工作流** (`.woodpecker/deploy.yml`) - 生产环境部署
- **质量门禁** (`.woodpecker/quality-gate.yml`) - 代码质量检查
### CI 触发条件
- 分支:`main``develop`
- 事件:`push``pull_request`
### 质量门禁标准
- ESLint 检查通过
- TypeScript 类型检查通过
- 单元测试覆盖率 ≥ 70%
- E2E 测试通过率 ≥ 95%
## 监控和告警
### Sentry 错误监控
项目集成了 Sentry 错误监控,用于追踪生产环境中的错误。
**配置环境变量:**
```env
NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
```
**监控内容:**
- JavaScript 错误
- API 错误
- 性能追踪
- 用户会话回放
### 健康检查
健康检查 API`GET /api/health`
**返回信息:**
- 应用状态
- 运行时间
- 内存使用
- 数据库连接状态
- 请求统计
### 性能监控
项目内置性能监控工具,记录关键指标:
- 响应时间(平均值、P50、P95、P99)
- 请求计数
- 内存使用率
**查看性能数据:**
```bash
curl http://localhost:3000/api/health
```
## 备份和恢复
### 备份
使用备份脚本定期备份数据:
```bash
./scripts/backup.sh
```
**备份内容包括:**
- SQLite 数据库文件
- 上传文件
- 环境配置
**备份文件位置:** `./backups/backup_YYYYMMDD_HHMMSS.tar.gz`
**自动清理:** 保留最近 7 天的备份
### 恢复
使用恢复脚本从备份中恢复数据:
```bash
./scripts/restore.sh <backup_file.tar.gz>
```
**注意事项:**
- 恢复操作会覆盖当前数据
- 恢复后需要重启应用
- 建议在恢复前先备份当前数据
## 性能测试
项目使用 k6 进行性能测试。
### 负载测试
模拟正常用户访问模式,测试系统在预期负载下的表现。
```bash
npm run test:performance
```
**测试场景:**
- 逐步增加用户数(100 → 200)
- 访问主要页面
- 提交联系表单
**性能指标:**
- P95 响应时间 < 500ms
- P99 响应时间 < 1000ms
- 错误率 < 1%
### 压力测试
测试系统在极端负载下的表现和极限。
```bash
npm run test:stress
```
**测试场景:**
- 快速增加用户数(50 → 300
- 持续高负载
- 快速下降
**性能指标:**
- P95 响应时间 < 1000ms
- P99 响应时间 < 2000ms
- 错误率 < 5%
**测试报告:** `tests/performance/load-test-summary.json`
## 安全测试
项目使用 k6 进行安全测试。
### SQL 注入测试
测试系统对 SQL 注入攻击的防护能力。
```bash
npm run test:sql-injection
```
**测试内容:**
- 常见 SQL 注入 payload
- UNION 查询注入
- 盲注攻击
- 时间注入
**防护措施:**
- 使用参数化查询(Drizzle ORM
- 输入验证和过滤
- 错误信息脱敏
### XSS 防护测试
测试系统对跨站脚本攻击的防护能力。
```bash
npm run test:xss
```
**测试内容:**
- Script 标签注入
- 事件处理器注入
- JavaScript 伪协议
- 外部资源引用
**防护措施:**
- 输入转义(DOMPurify
- CSP 策略
- HTTPOnly Cookie
### 完整安全测试
运行所有安全测试:
```bash
npm run test:security
```
## Docker 部署
项目提供 Docker 部署方案。
### 构建镜像
```bash
docker build -t novalon-website .
```
### 使用 Docker Compose
```bash
cp .env.production.example .env.production
docker-compose -f docker-compose.prod.yml up -d
```
### 健康检查
Docker 容器配置了健康检查:
```yaml
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
## 生产环境配置
### 环境变量
生产环境需要配置以下变量:
```env
# 数据库
DATABASE_URL=file:./data/prod.db
# NextAuth
NEXTAUTH_URL=https://novalon.cn
NEXTAUTH_SECRET=your-production-secret-here
# 管理员
ADMIN_EMAIL=admin@novalon.cn
ADMIN_PASSWORD=your-secure-password
# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
# 邮件服务
RESEND_API_KEY=your_resend_api_key
COMPANY_EMAIL=contact@novalon.cn
# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760
# 站点 URL
NEXT_PUBLIC_SITE_URL=https://novalon.cn
```
### 部署流程
1. **准备环境**
```bash
cp .env.production.example .env.production
# 编辑 .env.production 配置生产环境变量
```
2. **构建应用**
```bash
npm run build
```
3. **初始化数据库**
```bash
npm run db:push
npm run db:seed
```
4. **启动服务**
```bash
npm start
# 或使用 Docker
docker-compose -f docker-compose.prod.yml up -d
```
5. **验证部署**
```bash
curl http://localhost:3000/api/health
```
6. **配置监控**
- 在 Sentry 创建项目并配置 DSN
- 配置告警规则
7. **设置定时备份**
```bash
# 添加到 crontab
0 2 * * * /path/to/scripts/backup.sh
```
8. **配置CDN加速** (可选)
为静态资源配置CDN加速,提升网站加载速度:
```bash
# 配置CDN环境变量
export CDN_DOMAIN=https://cdn.novalon.cn
export COS_SECRET_ID=your-tencent-cloud-secret-id
export COS_SECRET_KEY=your-tencent-cloud-secret-key
export COS_BUCKET=novalon-cdn-1250000000
export COS_REGION=ap-chengdu
# 上传静态资源到COS
npm run deploy:cdn
# 刷新CDN缓存
npm run deploy:cdn:refresh
```
详细配置步骤请参考 [CDN配置文档](./docs/CDN_CONFIGURATION.md)
## 文档
详细文档位于 `docs/` 目录:
- [架构文档](docs/architecture.md) - 系统架构设计
- [组件文档](docs/components.md) - 组件使用指南
- [API 文档](docs/api.md) - API 接口说明
- [测试文档](docs/testing.md) - 测试策略和指南
- [部署文档](docs/deployment.md) - 部署流程说明
- [CMS文档](docs/cms.md) - CMS系统使用指南
## 许可证
Copyright © 2026 四川睿新致远科技有限公司
# Webhook test 2026年 3月28日 星期六 16时33分58秒 CST
# Auto trigger test 16:37:00
# Webhook test 16:47:05
# Test webhook after nginx fix 16:56:11
# Test with debug logging 16:59:24
# Final test after header fix 17:01:05
# Test after Gitea forge fix 17:14:00
# Final test with all fixes 17:23:42
# Complete CI/CD test 17:25:14
# v1.0.0 Release