跳转到主要内容

工作区管理员脚本和命令

清理数据库​

./scripts/clean-db.sh

通过删除所有数据来清理数据库，同时保留数据库模式和结构。

Caution

谨慎使用，因为这将删除所有现有数据。

清理构建产物和依赖项​

scripts/clean-workspace.sh

删除所有构建产物、node_modules 目录和其他生成的文件以确保干净状态。当您需要执行全新安装或解决依赖问题时，这很有用。该命令将删除：

  • node_modules/ 目录
  • .next/ 构建目录
  • dist/ 目录
  • out/ 目录
  • .turbo/ 目录
  • pnpm-lock.yaml
  • data/*.json（开发 JSON 备份文件）
  • public/documentation
  • documentation/.docusaurus、.cache、.cache-*、build、node_modules、pnpm-lock.yaml
  • .genkit/ 目录
  • *.tsbuildinfo 文件
  • pnpm 存储缓存（通过 pnpm store prune）
  • Docker 构建缓存和系统清理（镜像、网络、卷）

清理 Docker Compose 和 Docker 环境​

scripts/clean-docker.sh

执行完整的 Docker 清理，这对于以下情况很有用：

  • 释放磁盘空间
  • 删除旧的/未使用的 Docker 产物
  • 开发或测试会话后清理
  • 维护干净的 Docker 环境

将软件包更新到最新版本​

您可以使用以下方式手动更新包：

ncu --upgrade
pnpm update

或者使用自动化脚本（首选 source 以便 nvm 应用于当前 shell；对于 CI 或非交互式运行，请使用 CI=1 或 UPGRADE_ALLOW_EXEC=1）：

source ./scripts/upgrade-dependencies.sh

upgrade-dependencies.sh 脚本使整个依赖升级过程自动化。它是项目无关的：包管理器、工作区包和每个包的验证命令都是自动检测的（因此根目录和 documentation/ 包都会升级，没有硬编码路径）。它：

  • 通过 upgrade-tools.sh 源工具设置（nvm / Node LTS、全局 pnpm、npm-check-updates、doctoc）
  • 对每个包执行 build-safe 升级：npm-check-updates 解析最新版本，然后从工作区根目录进行安装和 typecheck/lint 运行。验证失败的升级通过编辑 package.json 进行二分（而不是 pnpm add，pnpm 在工作区根目录拒绝该文件）。嵌入的同级网关在 eslint-plugin-react / typescript-eslint 尚不允许最新主要版本时固定 eslint 和 typescript。
  • 更新工作区 pnpm 锁定文件并安装依赖项
  • 更新 browserslist 数据库
  • 检查漏洞（pnpm audit）并应用非破坏性修复（pnpm audit --fix）
  • 优先考虑安全：如果易受攻击的直接依赖项只能通过破坏构建的升级来修复，则强制应用安全版本并报告构建错误，以便代码可以更新以实现兼容性
  • 打印摘要（已升级与跳过的破坏构建的包、已修复/剩余的漏洞，以及用于手动回滚的清单快照路径）
  • 使用 /usr/bin/cp 复制 package.json 和锁定文件，这样源交互式 cp 别名（例如 cp -i）不会提示覆盖这些文件

此脚本提供了保持依赖项最新和安全的完整工作流程。

检查未使用的软件包​

pnpm depcheck

更新版本信息​

./scripts/update-version.sh

此脚本自动更新多个文件中的版本信息以保持同步。它：

  • 从 package.json 提取版本
  • 使用 VERSION 变量更新 .env 文件（如果不存在则创建）
  • 使用 VERSION 变量更新 Dockerfile （如果存在）
  • 更新 documentation/package.json 版本字段（如果存在）
  • 仅在版本已更改时更新
  • 提供每个操作的反馈

发布 GitHub Release​

pnpm release:github:dry
pnpm release:github

scripts/release.mjs 会在 HEAD 处为 v<package.json version> 打上标签，发布 GitHub Release（其发布说明来自 documentation/docs/release-notes/<version>.md，并重写为 RELEASE_NOTES_github_<version>.md），然后部署 Docusaurus 站点。请参阅发布管理。

预检查脚本​

./scripts/pre-checks.sh

此脚本在启动开发服务器、构建或启动生产服务器之前运行预检查。它：

  • 确保 .duplistatus.key 文件存在（通过 ensure-key-file.sh）
  • 更新版本信息（通过 update-version.sh）

此脚本由 pnpm dev、pnpm build 和 pnpm start-local 自动调用。

确保关键文件存在​

./scripts/ensure-key-file.sh

此脚本确保 .duplistatus.key 文件存在于 data 目录中。它：

  • 如果不存在则创建 data 目录
  • 如果缺失则生成新的 32 字节随机密钥文件
  • 将文件权限设置为 0400（仅所有者可读）
  • 如果权限不正确则修复权限

密钥文件用于应用程序中的加密操作。

管理员账户恢复​

./admin-recovery <username> <new-password>

此脚本允许在被锁定或忘记密码时恢复管理员账户。它：

  • 重置指定用户的密码
  • 如果账户被锁定则解锁
  • 重置失败登录尝试计数器
  • 清除"必须更改密码"标志
  • 验证密码是否满足安全要求
  • 将操作记录到审计日志中

示例：

./admin-recovery admin NewPassword123

Caution

此脚本直接修改数据库。仅在账户恢复必要时使用。

复制图像​

./scripts/copy-images.sh

将图像文件从 documentation/static/img 复制到应用程序中的适当位置：

  • 将 favicon.ico 复制到 src/app/
  • 将 duplistatus_logo.png 复制到 public/images/
  • 将 duplistatus_banner.png 复制到 public/images/

用于保持应用程序图像与文档图像同步。

切换本地或 npm ai-i18n-tools​

./scripts/link-ai-i18n-tools.sh --local
./scripts/link-ai-i18n-tools.sh --remote
pnpm i18n:tools --local
pnpm i18n:tools --remote

将此仓库指向同级的 ai-i18n-tools 检出或返回到发布的 npm 包，然后打印解析后的版本。--local 写入 link:../ai-i18n-tools （使用 --path 或 AI_I18N_TOOLS_PATH 覆盖路径），因此 pnpm i18n:* 和 ai-i18n-tools/runtime 都使用该树。--remote 安装最新 npm 版本作为 ^x.y.z。请勿提交 link: 说明符。

比较开发环境和 Docker 之间的版本​

./scripts/compare-versions.sh

此脚本比较您的开发环境和正在运行的 Docker 容器之间的版本。它：

  • 仅按主版本比较 SQLite 版本（例如，3.45.1 与 3.51.1 被视为兼容，显示为"✅ (major)"）
  • 精确比较 Node、npm 和 duplistatus 版本（必须完全匹配）
  • 显示显示所有版本比较的格式化表格
  • 提供带有颜色编码结果的摘要（✅ 表示匹配，❌ 表示不匹配）
  • 如果所有版本都匹配则以代码 0 退出，如果有不匹配则以代码 1 退出

要求：

  • 名为 duplistatus 的 Docker 容器必须正在运行
  • 脚本从 Docker 容器日志中读取版本信息

示例输出：

┌─────────────────────────┬──────────────────────────────┬──────────────────────────────┬──────────────┐
│ Component               │ Development                  │ Docker                       │   Match      │
├─────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────┤
│ SQLite                  │ 3.45.1                       │ 3.51.1                       │ ✅ (major)   │
│ Node                    │ 24.12.0                      │ 24.12.0                      │ ✅           │
│ npm                     │ 10.9.2                       │ 10.9.2                       │ ✅           │
│ Duplistatus             │ 1.2.1                        │ 1.2.1                        │ ✅           │
└─────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────┘

注意： SQLite 版本仅按主版本进行比较，因为同一主版本内的不同补丁版本通常兼容。脚本将指示 SQLite 版本在主版本级别是否匹配但补丁版本存在差异。

查看数据库 中的配置​

sqlite3 data/backups.db "SELECT key, value FROM configurations;" | awk -F'|' '
  {print "\n" $1 ": "; 
   if(index($2,"{")>0) {print $2 |"jq -C ."; close("jq -C .")} 
   else {print $2;}}' | less -R
sqlite3 /var/lib/docker/volumes/duplistatus_data/_data/backups.db "SELECT key, value FROM configurations;" | awk -F'|' '
  {print "\n" $1 ": "; 
   if(index($2,"{")>0) {print $2 |"jq -C ."; close("jq -C .")} 
   else {print $2;}}' | less -R

显示备份设置​

./scripts/show-backup-settings.sh [database_path]

以格式化表格显示配置表中 backup_settings 值的内容。用于调试通知配置很有用。默认数据库路径：data/backups.db。