纳格（Nage）

一个轻量、自托管的家庭 / 小团队物品收纳管理系统。

• 中文名：纳格（拼音：Nà gé）
• 英文名：Nage
• 版本：v1.4.0
• 栈：Next.js 16 · React 19 · SQLite · Drizzle ORM · Tailwind v4 · shadcn/ui
• 鉴权：管理员模式（无公开注册，账号由管理员后台创建）
• 部署：Docker Compose，反代 BYO（Caddy / Nginx / Cloudflare Tunnel 任选）
• 数据库：单文件 SQLite（data/nage.db）
• 许可：GPL v3

特性

• 📦 物品管理：图片、价格、描述、数量、过期时间，列表/卡片双视图 + 标签 + 分类
• 🌲 5 级位置树：父级位置可折叠展开，跨级拖拽排序
• 🏷 彩色标签：多对多关联
• ⏰ 过期提醒：仪表盘「快过期」卡片，30 天 / 7 天 / 已过期三档颜色
• 📱 移动端优先：底部 Tab + 触控 ≥ 44px，PC 端侧栏
• 🔍 搜索 + 筛选：跨字段模糊搜索 + 位置/分类/标签/过期多维筛选 + 排序分页
• 📷 二维码：每件物品一个，扫码直达详情
• 📥 数据导入导出：JSON 格式，跨实例可迁移
• 👥 多用户/多空间协作（v1.1）：一个空间可有多成员，三档角色（owner / editor / viewer），顶栏切换空间
• 🔐 管理员模式：无公开注册，账号由管理员创建，密码 bcrypt 哈希，登录 5 次失败锁 10 分钟
• 🐳 一键部署：Docker Compose，应用只听 :3000；HTTPS 由你的反代负责
• 💾 热备份：sqlite3 .backup 在线备份，30 天滚动，cron 自动

快速开始（开发）

# 1. 装依赖
pnpm install

# 2. 复制环境变量模板
cp .env.local.example .env.local
# 首次启动会读 ADMIN_USERNAME / ADMIN_PASSWORD 自动建管理员
# 不填就随机生成并打印在控制台

# 3. 起开发服
pnpm dev
# 打开 http://localhost:3000

E2E 测试

pnpm dev   # 另一个终端
node node_modules/tsx/dist/cli.mjs scripts/test-http.ts
node node_modules/tsx/dist/cli.mjs scripts/test-crud.ts
node node_modules/tsx/dist/cli.mjs scripts/test-flow.ts
node node_modules/tsx/dist/cli.mjs scripts/test-items.ts

部署到公网

完整文档：DEPLOY.md

1 台 VPS + Docker Compose，反代自己挑（示例）：

# 1. 准备：DNS 解析、装 Docker、复制代码到 /opt/nage
# 2. 配 .env（必须设 ADMIN_PASSWORD / JWT_SECRET）
# 3. 起 Nage
docker compose up -d --build
# 4. 验证 Nage 本身通了
curl -I http://127.0.0.1:3000/login   # 应返回 200
# 5. 架反代（Caddy / Nginx / Cloudflare Tunnel 任选）
#    按 docs/examples/ 里对应文档配

备份：

bash scripts/backup.sh         # 手动
# 0 3 * * * cd /opt/nage && bash scripts/backup.sh >> logs/backup.log 2>&1   # crontab

恢复：

docker compose stop app
docker exec -it nage-app bash /app/scripts/restore.sh
docker compose start app

项目结构

src/
  app/
    (auth)/login/         # 登录页
    (app)/                # 登录后布局（顶栏 + 移动 Tab + 侧栏）
      page.tsx            # 仪表盘
      items/              # 物品 CRUD
      locations/          # 位置（5 级树）
      categories/         # 分类
      tags/               # 标签
      admin/members/      # 成员管理（仅管理员）
      admin/data/         # 数据导入/导出（owner/editor 可操作自己空间）
    spaces/               # 空间设置 + 新建空间（v1.1）
  lib/
    db/                   # Drizzle schema + 实例
    auth/                 # JWT / 密码 / session / bootstrap
    actions/              # Server Actions（CRUD）
    validation/           # zod schemas
  components/
    ui/                   # shadcn 组件
    layout/               # 顶栏、侧栏、Tab、FAB
data/nage.db              # SQLite（gitignore）
data/uploads/             # 用户上传图片（v1.4.0 M10 后从 public/uploads/ 迁出）
scripts/                  # E2E 测试 + 备份/恢复

里程碑

• M1 鉴权 + 空间/位置/分类/标签/成员 CRUD + UI 骨架
• M2 物品 CRUD + 图片上传 + 搜索筛选
• M3 仪表盘（最近更新 + 快过期）
• M4 二维码 + 扫码 + 数据导入导出
• M5 Docker 化 + 备份脚本 + 部署文档（反代 v1.0.1 起 BYO）
• M7 多用户/多空间协作（v1.1.0）：多空间 + 三档角色 + 空间设置 + 空间切换器 + 导入导出放宽
• v1.2 借出归还 / 保质期增强 / PWA / i18n

详细变更历史见 CHANGELOG.md。 部署指南见 DEPLOY.md。 产品规范见 PRD.md。

详细规范

设计细节、数据模型、版本规划见 PRD.md。 项目协作约束见 CLAUDE.md。