跳转到主要内容

开发设置

先决条件​

  • Docker / Docker Compose
  • Node.js（参见 engines.node 中的 package.json）
  • pnpm（参见 engines.pnpm / packageManager 中的 package.json）
  • SQLite3
  • Inkscape（用于文档 SVG 翻译和 PNG 导出；仅在运行 translate 或 translate:svg 时需要）
  • bat/batcat（用于显示漂亮的 translate:help 版本）
  • direnv（用于自动加载 .env* 文件）
  • Playwright Chromium（在 pnpm install 后运行 pnpm take-screenshots:install；这将运行 playwright install chromium）

步骤​

1. 克隆仓库：​

git clone https://github.com/wsj-br/duplistatus.git
cd duplistatus

2. 安装依赖项（Debian/Ubuntu）：​

sudo apt update
sudo apt install sqlite3 git inkscape bat -y
sudo apt install -y build-essential python3 python3-dev python3-setuptools make g++ gcc pkg-config

3. 删除旧的 Node.js 安装（如果已安装）​

sudo apt-get purge nodejs npm -y
sudo apt-get autoremove -y
sudo rm -rf /usr/local/bin/npm 
sudo rm -rf /usr/local/share/man/man1/node* 
sudo rm -rf /usr/local/lib/dtrace/node.d
rm -rf ~/.npm
rm -rf ~/.node-gyp
sudo rm -rf /opt/local/bin/node
sudo rm -rf /opt/local/include/node
sudo rm -rf /opt/local/lib/node_modules
sudo rm -rf /usr/local/lib/node*
sudo rm -rf /usr/local/include/node*
sudo rm -rf /usr/local/bin/node*

4. 安装 Node.js 和 pnpm：​

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
npm config set allow-scripts=pnpm --location=user
npm install -g pnpm npm-check-updates doctoc

5. 设置 direnv 支持​

将这些行添加到您的 ~/.bashrc 文件中

# direnv support (apt install direnv)
eval "$(direnv hook bash)"

使用此命令：

(echo "# direnv support (apt install direnv)"; echo 'eval "$(direnv hook bash)') >> ~/.bashrc

在仓库基础目录中运行：

direnv allow

将这些行添加到您的 ~/.profile 文件中

# export the Bash environment (needed for code editor or AI Agents to load it).
export BASH_ENV="$HOME/.bashrc"

使用此命令：

(echo "# export the Bash environment (needed for code editor or AI Agents to load it)."; \
 echo 'export BASH_ENV="$HOME/.bashrc"') >> ~/.profile
信息

您需要重新打开终端或可能需要关闭/重新打开代码编辑器 IDE（Visual Studio Code、 Cursor、Lingma、Antigravity、Zed，...），以便使这些更改生效。

6. 在仓库基础目录创建包含这些变量的 .env 文件。​

  • 您可以为 VERSION 使用任何值；使用开发脚本时它将自动更新。

  • 为 ADMIN_PASSWORD 和 USER_PASSWORD 使用随机密码；这些密码将在 pnpm take-screenshots 脚本中使用。

  • 您可以从 openrouter.ai 获取 OPENROUTER_API_KEY。

    VERSION=x.x.x

    # Development user passwords
    ADMIN_PASSWORD="admin_secret"
    USER_PASSWORD="user_secret"


    # Openrouter.ai API key for translation scripts in documentation 
    OPENROUTER_API_KEY=sk-or-v1-your-key-for-translate-files

可用脚本​

项目包含几个用于不同开发任务的 npm 脚本：

开发脚本​

  • pnpm dev - 同时启动 Next.js 开发服务器（端口 8666）和 cron 服务（端口 8667），通过 concurrently 运行（包含预检查）。按 CTRL-C 可停止两者。Next.js 的 NODE_OPTIONS 加载 scripts/dev-preload.cjs，应用 scripts/peer-ip.cjs（IP 白名单的 TCP 对等地址）和请求日志时间戳。
  • pnpm dev:next - 仅在端口 8666 上启动 Next.js 开发服务器（无 cron）。
  • pnpm build - 构建用于生产的应用程序（包含预检查）
  • pnpm lint - 运行 ESLint 检查代码质量
  • pnpm typecheck - 运行 TypeScript 类型检查
  • scripts/upgrade-dependencies.sh — 安全构建升级所有工作区包（自动检测）。使用 npm-check-updates 解析最新版本，在工作区根目录安装，并且只保留能通过每个包的 typecheck/lint 的升级（对等门钉住 eslint / typescript 当 lint 栈不允许最新的主要版本时）。然后运行 pnpm audit / audit --fix 并强制应用（并报告）任何需要代码更改的安全修复。刷新工作区锁定文件和 browserslist。建议使用 source ./scripts/upgrade-dependencies.sh 以便 nvm 应用于您的 shell；在 CI 或自动化中直接执行文件时使用 CI=1 或 UPGRADE_ALLOW_EXEC=1。另请参见仅限 Node/pnpm 工具的 scripts/upgrade-tools.sh。
  • scripts/clean-workspace.sh - 清理工作区
  • pnpm i18n:tools --local / --remote — 链接同级 ai-i18n-tools 检出或恢复最新的 npm 包（scripts/link-ai-i18n-tools.sh）。请勿提交 link: 说明符。

注意： preinstall 脚本会自动强制使用 pnpm 作为包管理器。

文档脚本​

这些脚本必须从 documentation/ 目录运行：

  • pnpm start - 在生产模式下构建并提供文档站点（默认端口 3000）
  • pnpm start:en - 以英语启动文档开发服务器（启用热重载）
  • pnpm start:fr - 以法语区域设置启动文档开发服务器（启用热重载）
  • pnpm start:de - 以德语区域设置启动文档开发服务器（启用热重载）
  • pnpm start:es - 以西班牙语区域设置启动文档开发服务器（启用热重载）
  • pnpm start:pt-br - 以葡萄牙语（巴西）区域设置启动文档开发服务器（启用热重载）
  • pnpm build - 为生产构建文档站点
  • pnpm write-translations - 从文档中提取可翻译字符串
  • pnpm translate - 使用 AI 翻译文档文件（参见翻译工作流程）
  • pnpm lint - 对文档源文件运行 ESLint

开发服务器（start:*）提供快速开发的热模块替换。默认端口是 3000。

生产脚本​

  • pnpm build-local - 构建并准备本地生产环境（包括预检查，将静态文件复制到独立目录）
  • pnpm start-local - 在本地启动生产服务器（端口 8666，包括预检查）。注意： 先运行 pnpm build-local。使用 --require ./scripts/peer-ip.cjs 启动独立服务器。
  • pnpm start - 使用相同的 peer-ip 预加载启动生产服务器（端口 9666）。Docker 使用 docker-entrypoint.sh 来加载相同脚本。

Docker 脚本​

  • pnpm docker:up - 启动 Docker Compose 堆栈
  • pnpm docker:down - 停止 Docker Compose 堆栈
  • pnpm docker:clean - 清理 Docker 环境和缓存
  • pnpm docker:devel - 构建标记为 wsj-br/duplistatus:devel 的开发 Docker 镜像

Cron 服务脚本​

  • pnpm cron:start - 在生产模式下启动 cron 服务
  • pnpm cron:dev - 在开发模式下启动仅 cron 服务并启用文件监视（端口 8667）。通常在使用 pnpm dev 时不需要，因为它已经启动了 cron。
  • pnpm cron:start-local - 在本地启动 cron 服务进行测试（端口 8667）

测试脚本​

  • pnpm generate-test-data - 生成测试备份数据（需要 --servers=N 参数）
  • pnpm validate-csv-export - 验证 CSV 导出功能
  • pnpm test-entrypoint - 在本地开发中测试 Docker 入口点脚本（参见测试脚本）
  • pnpm take-screenshots - 为文档截取屏幕截图（参见文档工具）

逾期检查、cron 健康检查和 SMTP 测试通过正在运行的应用程序和 curl 进行（参见测试脚本）；旧的独立 pnpm 辅助工具已被移除。