# show-project

**Repository Path**: unihao/show-project

## Basic Information

- **Project Name**: show-project
- **Description**: 开源项目集 · 个人开源项目展示站
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开源项目集 · 个人开源项目展示站

聚合展示个人开源项目的轻量网站。一期已实现：首页、项目列表与搜索筛选、项目详情、Agent Skills 展示、后台登录、项目/分类/Skill 管理、封面上传与富文本编辑。

**技术栈**：Vue 3 + Vite + Element Plus + Pinia / Express 5 + `node:sqlite` + JWT + multer。

**开源协议**：MIT，见 [LICENSE](./LICENSE)。

数据落在一个 SQLite 文件里，靠 Node 内置的 `node:sqlite` 访问 —— 全项目**没有任何需要编译的原生依赖**，不需要安装 MySQL，`npm install` 就能跑起来。

---

## 快速开始

前置：Node.js **≥ 23.4**（已在 v24.16.0 验证）。低于此版本 `node:sqlite` 需要额外启动参数。

```bash
npm install     # 安装依赖
npm run dev     # 同时启动后端(3001) 与 前端(5173)
```

打开 http://localhost:5173

首次启动会自动建库、建表并播种初始数据，**无需任何手工配置**。默认管理员：

| 用户名 | 密码 |
|---|---|
| `admin` | `admin123` |

> **首次登录后请立刻修改密码**：后台右上角 → 修改密码。（服务端启动时会检查是否仍是默认口令并打印告警。）

## 管理后台入口

前台刻意**不放置**后台入口链接，需要自己敲地址进入：

```
开发：http://localhost:5173/#/admin/login
生产：http://localhost:3001/#/admin/login   （换成你的域名）
```

两个注意点：

1. 本项目是 **hash 路由**，`#` 不能漏。写成 `/admin/login` 会被服务端 SPA fallback 打回首页，看起来像"点了没反应"。
2. 已登录状态下访问登录页会自动跳进后台，反之未登录访问 `/#/admin/projects` 会被拦到登录页，登录成功后回到原来要去的地方。

后台里可以管理项目、分类和 Agent Skills。「新建项目」按钮在项目列表页右上角，不在侧栏菜单。

## 常用命令

| 命令 | 说明 |
|---|---|
| `npm run dev` | 并行启动后端(3001) 与前端开发服务器(5173)，前端 `/api` 自动代理到后端 |
| `npm run build` | 构建前端产物到 `client/dist` |
| `npm start` | 生产模式启动 Express，托管 `client/dist` 并提供 REST API，单进程监听 3001 |
| `npm test` | 运行后端测试（`node:test`，使用内存数据库，不污染真实数据文件） |
| `npm run dev:server` / `npm run dev:client` | 只启动后端 / 只启动前端 |

## 环境变量

复制到项目根目录的 `.env` 后按需修改（可参考 `server/.env.example`）。**全部变量都有默认值，不配置也能正常启动**。

| 变量 | 默认值 | 说明 |
|---|---|---|
| `PORT` | `3001` | 服务监听端口 |
| `JWT_SECRET` | 随机生成 | JWT 签名密钥。不设置时每次服务重启都会生成新的，导致已登录用户被强制登出，**生产环境务必固定** |
| `DB_FILE` | `server/data/app.db` | SQLite 数据文件路径 |
| `ADMIN_DEFAULT_PASSWORD` | `admin123` | 首次迁移时创建的默认管理员口令 |
| `LOGIN_LIMIT` | `20` | 登录接口限流（15 分钟内每 IP 次数）。生产建议调到 `5` |
| `API_LIMIT` | `300` | 全接口限流（15 分钟内每 IP 次数） |
| `UPLOAD_LIMIT` | `30` | 上传接口限流（1 小时内每 IP 次数） |
| `NODE_ENV` | 空（开发态） | 设为 `production` 后进入生产态，见下方「演示数据」 |
| `SEED_DEMO` | 跟随 `NODE_ENV` | 强制开关演示数据：`1` 写入 / `0` 跳过，优先级高于 `NODE_ENV` |

## 目录结构

```
server/                  Express REST API
  src/config.js          配置（环境敏感项做成惰性 getter，便于测试）
  src/db/                连接、schema.sql、迁移与种子数据（幂等）
  src/services/          业务逻辑，唯一触达数据库的一层
  src/controllers/       取参 → 调 service → 统一响应
  src/routes/            路由，公开路由与 /admin 路由分离
  src/middleware/        鉴权、限流、上传、错误兜底
  src/utils/             密码哈希、富文本清洗、slug、统一响应、日志
  data/app.db            SQLite 数据文件（已被 git 忽略）
  uploads/               上传图片（已被 git 忽略）
client/                  Vue3 前端
  src/views/front/       首页、项目列表、详情
  src/views/admin/       登录、项目列表、项目编辑、分类管理
  src/api/               axios 封装与各模块接口
docs/superpowers/        设计与实施文档
```

## 安全说明

- 密码用 bcrypt 哈希存储，永不明文落库或返回前端。
- 富文本入库前经过白名单清洗，剥离 `<script>`、`on*` 事件属性、`javascript:` 协议。
- 所有 SQL 使用参数化查询，杜绝注入。
- 上传限制：仅 JPG/PNG/WebP/GIF，≤5MB，随机文件名，路径穿越不可行。
- `helmet` 安全头（关闭了 CSP，因为后台编辑器依赖内联样式；如需 CSP 建议在 Nginx 层精细配置）+ 登录/上传/全局三档限流。
- 生产请在 Nginx / 宝塔层终止 HTTPS 并配置反向代理。

### Nginx 反代样例

```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 部署

### Docker Compose（推荐）

容器内固定以生产模式运行（`NODE_ENV=production`），前端在镜像里构建，宿主机不需要装 Node，也不用手动跑 `npm run build`。

**1. 准备环境变量**

```bash
cp .env.example .env
```

把 `JWT_SECRET` 填上一串随机值，**留空会直接拒绝启动**：

```bash
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
```

**2. 构建并启动**

```bash
docker compose up -d --build
docker compose logs -f      # 看启动日志，确认打印了"跳过演示数据"
docker compose ps           # 看健康检查状态
```

默认访问 http://localhost:3001 ，改宿主机端口调 `.env` 里的 `HOST_PORT`。

**3. 更新代码后重新部署**

```bash
docker compose up -d --build
docker image prune -f       # 可选，清掉旧镜像层
```

数据库和上传目录落在两个命名卷 `app-data` / `app-uploads` 上，容器重建不会丢数据，备份方式见文末「备份」。

### 直接 Node 启动

```bash
npm install
npm run build
NODE_ENV=production npm start      # Linux / macOS
```

Windows PowerShell 写法（没有 `NODE_ENV=x` 语法）：

```powershell
$env:NODE_ENV='production'; npm start
```

用 pm2 常驻（`server/ecosystem.config.js` 里已写好 `NODE_ENV=production`，无需再设环境变量）：

```bash
npm i -g pm2
pm2 start server/ecosystem.config.js
pm2 save
```

### 演示数据

首次启动（全新数据库）时是否写入示例项目，取决于运行态：

| 场景 | 行为 |
|---|---|
| `NODE_ENV=production` | **只建骨架**：管理员、分类字典、站点默认配置。项目表为空，站点社交链接为空 |
| 未设置 / `development` | 骨架 + 2 个示例项目 + 6 个示例 Skill + 示例 GitHub / Gitee 外链 |
| `SEED_DEMO=1` | 强制写入演示数据，用于生产环境临时演示 |
| `SEED_DEMO=0` | 强制跳过演示数据 |

启动时日志会明确打印走了哪条分支，便于确认。

注意两点：

1. 演示数据只在**全新数据库**初始化时写入，已存在的库不会因为重启而反复插入。
2. 如果你手上已经有开发期生成的 `server/data/app.db`，直接拿去生产部署会带着那 2 条示例项目上线。两种处理办法：换一个新库路径（`DB_FILE` 指向新文件），或在后台「项目列表」里把这两条删掉。

分类字典（Java / Go / Python 等）属于站点结构而非演示内容，生产也会写入，可在后台「分类管理」自行增删。

## 备份

所有可变数据只有两处，**备份就是复制这两个东西**：

```bash
tar czf backup-$(date +%F).tar.gz server/data/app.db server/uploads/
```

恢复时解压回原路径并重启服务即可。

Docker 部署时数据在两个命名卷里，卷名带 compose 项目名前缀（默认取目录名），可以这样备份：

```bash
docker run --rm \
  -v open-source-showcase_app-data:/data \
  -v "$PWD":/backup alpine \
  tar czf /backup/backup-$(date +%F).tar.gz -C /data .

docker volume ls        # 不确定卷名时先查一下
```

## 已知限制

- 生产构建的首屏 JS 约 870KB（gzip 后约 277KB），主要来自全量引入的 Element Plus。个人站访问量下可接受；若要优化，可用 `unplugin-vue-components` 改为按需引入。
- 一期**不包含**以下模块（需求文档中列为二期）：个人动态时间线、关于我页面、留言板及其后台管理、站点配置的后台编辑界面。站点配置目前由迁移脚本播种，可在 `server/src/db/seed.js` 修改后重新初始化数据库。