Signature Wall 联合签名墙

一个可自托管的活动签名收集应用。参与者可以在手机或桌面浏览器中手写签名、上传签名图片并选择 A4 版面位置；管理员可以管理征集流程、生成两页 A4 PDF，并在确认成品后清理原始数据。

功能

• 网页手写、横屏全屏书写和图片上传
• 自动去除图片白底，保留黑色透明签名
• 两页 A4 共 40 个固定位置，移动端可视化选位
• 一次性撤回凭证，可修改或删除自己的签名
• 管理后台控制开放、关闭、发布和下载状态
• 浏览器端高分辨率渲染并生成两页 A4 PDF
• SQLite 本地存储、数据库备份和原始数据永久清理
• Session、CSRF、速率限制、安全响应头和生产配置校验
• 自签名 HTTPS，或部署在 Nginx 等反向代理之后

快速开始

需要 Node.js 22 或更高版本。

git clone https://github.com/help660vip/signature-wall.git
cd signature-wall
npm ci
cp .env.example .env
npm run dev

Windows PowerShell 可用 Copy-Item .env.example .env 复制配置。默认开发地址为 https://localhost:18888；首次访问时，浏览器会提示本地自签名证书不受信任。

• 参与者入口：https://localhost:18888/demo-invite
• 管理员入口：https://localhost:18888/admin
• 示例管理员密码：change-this-admin-password

.env.example 中的凭据只用于本地体验，不可直接用于公网部署。

生产配置

复制 .env.example 后，至少修改以下配置：

变量	说明
NODE_ENV	生产环境设为 production
BASE_URL	对外访问的完整 HTTPS 根地址
SESSION_SECRET	至少 32 个随机字符，用于会话与撤回凭证 HMAC
INVITE_CODE	8-64 位字母、数字、连字符或下划线
ADMIN_PASSWORD	至少 12 个字符的独立管理员密码
EVENT_TITLE	活动标题
EVENT_SUBTITLE	活动副标题
EVENT_DATE	页面及 PDF 显示日期
WATERMARK_TEXT	PDF 水印文字

可以用 OpenSSL 生成随机会话密钥：

openssl rand -hex 32

直接由 Node 提供 HTTPS 时，保持 TLS_ENABLED=true。首次启动会在 data/tls/ 生成并复用自签名证书；也可以通过 TLS_CERT_PATH 和 TLS_KEY_PATH 指定已有证书。

由 Nginx 终止 TLS 时，建议使用以下组合，让 Node 只监听本机：

NODE_ENV=production
HOST=127.0.0.1
BASE_URL=https://signature.example.com
TRUST_PROXY=1
SECURE_COOKIE=true
TLS_ENABLED=false

反向代理示例见 deploy/nginx.conf.example，完整部署与运维说明见项目开发交接与维护手册。

构建与运行

npm ci
npm run check
npm test
npm run build
npm start

PM2 单实例运行示例：

mkdir -p data/logs
pm2 start ecosystem.config.cjs
pm2 save

应用使用本地 SQLite，PM2 不应开启 cluster 模式。Linux 环境也可以运行 bash deploy/install-linux.sh 完成依赖安装、构建和原生模块冒烟检查。

常用命令

命令	用途
npm run dev	构建并以监听模式启动开发服务器
npm run check	TypeScript 静态检查
npm test	运行单元与接口测试
npm run test:e2e	运行桌面、Android 和 iPhone 浏览器测试
npm run build	生成 dist/ 构建产物
npm run check:linux	检查 Linux 原生依赖和构建产物
npm run backup	创建 SQLite 一致性备份
npm run reset -- --confirm	备份后重置活动数据

首次运行端到端测试前，需要安装 Playwright WebKit：

npx playwright install webkit

数据与隐私

运行数据统一保存在 data/，包括 SQLite 数据库、备份、日志和自动生成的证书。该目录以及 .env 已被 Git 忽略，不应提交到仓库。

上传的原始图片只在请求内存中处理，数据库保存去白底后的 PNG。活动发布最终 PDF 后，管理员可以执行永久清理，删除原始笔迹、处理图、撤回凭证和参与者会话，只保留最终 PDF。执行清理前请先运行 npm run backup 并验证备份。

项目结构

src/       服务端、数据访问、安全逻辑和浏览器端 TypeScript
views/     EJS 页面模板
public/    公共样式
scripts/   构建、备份、重置和测试辅助脚本
tests/     Vitest 接口测试与 Playwright 端到端测试
deploy/    Linux 安装脚本和 Nginx 配置示例
*.md       维护手册与 iOS 客户端对接文档

文档

• 项目开发交接与维护手册
• iOS 原生客户端对接文档