常见问题

Webooks 是一个现代化的书签管理工具，支持智能导入、分类管理、高级搜索等功能。您可以从各种浏览器导入书签，创建分类空间，快速查找所需网站。

主要特性包括：

• 智能书签导入和自动分类
• 空间和文件夹管理
• 全文搜索和高级筛选
• 浏览器扩展支持
• RESTful API 支持

是的，Webooks 是一个开源项目，完全免费使用。遵循 MIT 许可证，您可以自由使用、修改和分发。

您可以：

• 在个人项目中免费使用
• 修改源代码以满足需求
• 部署到自己的服务器
• 贡献代码和改进建议

Webooks 支持所有现代浏览器，包括：

• Chrome/Chromium： 完全支持，包括扩展
• Firefox： 完全支持，包括扩展
• Safari： 基本支持（某些功能可能受限）
• Edge： 完全支持
• 移动浏览器： 响应式设计支持

Webooks 非常重视数据安全：

• 本地部署： 数据完全存储在您的服务器上
• 加密传输： 所有 API 调用使用 HTTPS
• 身份认证： JWT 令牌机制
• 数据备份： 支持数据库备份和恢复

最低系统要求：

• Node.js 18.x 或更高版本
• PostgreSQL 13+ 或 SQLite（开发环境）
• 1GB RAM
• 5GB 磁盘空间

推荐配置：

• Node.js 20.x LTS
• PostgreSQL 15+
• 2GB+ RAM
• 20GB+ SSD 存储

安装失败的常见原因和解决方案：

1. Node.js 版本问题

# 检查 Node.js 版本
node --version

# 如果版本过低，更新 Node.js
nvm install 20
nvm use 20

2. 依赖安装失败

# 清理缓存后重新安装
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

3. 数据库连接问题

# 检查数据库是否运行
sudo systemctl status postgresql

# 启动数据库服务
sudo systemctl start postgresql

4. 权限问题

# 在 Linux/macOS 上
sudo chown -R $USER:$USER .

# 或使用管理员权限（Windows）
# 右键点击命令提示符，选择"以管理员身份运行"

安装成功后，可以通过以下方式验证：

1. 启动开发服务器

npm run dev

如果看到 "Local: http://localhost:3000" 则表示启动成功。

2. 访问应用

在浏览器中打开 http://localhost:3000，应该能看到 Webooks 登录页面。

3. 检查控制台

打开浏览器开发者工具，查看控制台是否有错误信息。

4. 数据库连接测试

# 测试数据库连接
npx prisma db push

# 如果没有错误信息，则连接正常

Webooks 支持 PostgreSQL 和 SQLite。

PostgreSQL 配置（推荐）

# .env 文件
DATABASE_URL="postgresql://username:password@localhost:5432/webooks"

# 创建数据库（如果不存在）
createdb webooks

SQLite 配置（开发环境）

# .env 文件
DATABASE_URL="file:./dev.db"

数据库迁移

# 生成 Prisma 客户端
npx prisma generate

# 创建数据库表
npx prisma db push

# 查看数据库
npx prisma studio

JWT 密钥用于用户身份认证，建议使用强密钥：

生成强密钥

# 使用 Node.js 生成
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

# 或使用在线工具
# https://www.grc.com/passwords.htm

配置 .env 文件

# .env 文件
JWT_SECRET="your-super-secret-jwt-key-here"
# 密钥至少 32 字符，建议 64+ 字符

默认情况下，Webooks 运行在 3000 端口。您可以通过环境变量修改：

# .env 文件
PORT=3001

# 或在启动时指定
PORT=3001 npm run dev

如果端口被占用，系统会自动选择下一个可用端口。

Webooks 支持多种导入方式：

1. HTML 文件导入

1. 从浏览器导出书签为 HTML 文件
2. 在 Webooks 中进入"导入"页面
3. 选择 HTML 文件并上传
4. 选择目标空间和文件夹
5. 点击"开始导入"

2. 浏览器扩展导入

1. 安装 Webooks 浏览器扩展
2. 点击扩展图标
3. 选择"导入当前标签页"
4. 或选择"导入所有书签"

3. API 导入

# 使用 curl 命令导入
curl -X POST "http://localhost:3000/api/bookmarks/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@bookmarks.html" \
  -F "spaceId=space_123"

导入失败的常见原因和解决方案：

文件格式问题

• 确保书签文件是浏览器导出的标准 HTML 格式
• 检查文件编码是否为 UTF-8
• 文件大小不超过 10MB

网络问题

• 检查网络连接是否正常
• 确保防火墙没有阻止连接
• 尝试刷新页面重试

权限问题

• 确保用户已登录
• 检查目标空间权限
• 尝试在其他浏览器中导入

重复书签处理

• 系统会自动检测重复书签
• 可以在导入设置中选择重复处理策略
• 重复书签不会被重复导入

Webooks 提供多种导出方式：

1. 通过网页界面导出

1. 进入书签管理页面
2. 选择要导出的书签（可选）
3. 点击"导出"按钮
4. 选择导出格式（HTML/JSON）
5. 下载导出文件

2. API 导出

# 导出所有书签为 HTML
curl -X GET "http://localhost:3000/api/bookmarks/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o bookmarks_export.html

# 导出特定空间的书签
curl -X GET "http://localhost:3000/api/bookmarks/export?spaceId=space_123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o space_bookmarks.html

3. 导出格式

• HTML 格式： 标准浏览器书签格式，可在所有浏览器中导入
• JSON 格式： 结构化数据，适合程序处理
• CSV 格式： 表格数据，可在 Excel 中打开

Webooks 支持实时同步功能：

自动同步

• 书签变更后会自动同步
• 支持多设备数据一致性
• 同步延迟通常在 1-3 秒内

手动同步

• 在设置中点击"强制同步"
• 或按 F5 刷新页面

冲突处理

• 同时编辑冲突时，系统会保留最新更改
• 可通过版本历史恢复历史版本
• 重要操作前建议备份数据

同步问题的诊断和解决：

网络连接问题

• 检查网络连接是否正常
• 尝试切换网络（如使用手机热点）
• 检查防火墙设置

服务器问题

• 检查服务器是否正常运行
• 查看服务器日志了解具体错误
• 联系服务器管理员

客户端问题

• 清理浏览器缓存
• 禁用浏览器扩展（可能是冲突源）
• 尝试无痕/隐私模式

数据库问题

• 检查数据库连接是否正常
• 验证数据库权限
• 检查磁盘空间是否充足

Webooks 支持多用户权限管理：

用户角色

• 管理员： 全部权限，可管理用户和系统设置
• 编辑者： 可创建、编辑、删除书签
• 查看者： 仅可查看书签，无法修改

设置用户权限

1. 登录管理员账户
2. 进入用户管理页面
3. 选择目标用户
4. 修改角色和权限设置
5. 保存更改

空间权限

• 每个空间可设置独立的访问权限
• 支持公开和私有空间
• 可邀请特定用户访问私有空间

定期备份是保护数据的重要措施：

PostgreSQL 备份

# 备份整个数据库
pg_dump webooks > backup_$(date +%Y%m%d_%H%M%S).sql

# 备份指定表
pg_dump -t bookmarks webooks > bookmarks_backup.sql

# 压缩备份
pg_dump webooks | gzip > backup_$(date +%Y%m%d).sql.gz

自动备份脚本

#!/bin/bash
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="webooks"
DB_USER="webooks_user"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 执行备份
pg_dump -U $DB_USER -h localhost $DB_NAME | gzip > "$BACKUP_DIR/webooks_$DATE.sql.gz"

# 删除 7 天前的备份
find $BACKUP_DIR -name "webooks_*.sql.gz" -mtime +7 -delete

echo "备份完成: webooks_$DATE.sql.gz"

SQLite 备份

# 简单的文件复制
cp dev.db backup_$(date +%Y%m%d_%H%M%S).db

# 或使用 SQLite 命令
sqlite3 dev.db ".backup backup_$(date +%Y%m%d_%H%M%S).db"

数据库恢复步骤：

PostgreSQL 恢复

# 停止应用
pm2 stop webooks

# 创建新数据库（如果需要）
createdb webooks_restored

# 恢复数据
psql webooks_restored < backup_20241201_120000.sql

# 或从压缩文件恢复
gunzip -c backup_20241201.sql.gz | psql webooks_restored

# 更新 .env 文件中的数据库配置
# DATABASE_URL="postgresql://user:pass@localhost:5432/webooks_restored"

# 重启应用
pm2 restart webooks

SQLite 恢复

# 停止应用
pm2 stop webooks

# 恢复数据库文件
cp backup_20241201_120000.db dev.db

# 重启应用
pm2 restart webooks

数据库连接超时的常见原因和解决方案：

连接字符串错误

# 检查 .env 文件中的数据库连接字符串
DATABASE_URL="postgresql://username:password@localhost:5432/webooks"

# 确保：
# 1. 用户名和密码正确
# 2. 主机地址正确（localhost/127.0.0.1/其他）
# 3. 端口号正确（PostgreSQL 默认 5432）
# 4. 数据库名称正确

数据库服务未启动

# 检查 PostgreSQL 服务状态
sudo systemctl status postgresql

# 启动 PostgreSQL 服务
sudo systemctl start postgresql

# 设置开机自启
sudo systemctl enable postgresql

防火墙阻止连接

# 检查防火墙设置
sudo ufw status

# 允许 PostgreSQL 连接
sudo ufw allow 5432/tcp

连接数限制

# 检查 PostgreSQL 最大连接数
sudo -u postgres psql -c "SHOW max_connections;"

# 检查当前连接数
sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"

网站性能优化的建议：

服务器优化

• 增加内存： 推荐至少 2GB RAM
• 使用 SSD： 提升磁盘 I/O 性能
• 启用压缩： 在 Nginx 中启用 gzip 压缩
• CDN 加速： 静态资源使用 CDN

应用优化

• 数据库优化： 添加适当的索引
• 缓存策略： 启用浏览器缓存
• 图片优化： 压缩图片，使用 WebP 格式
• 代码分割： Next.js 自动代码分割

Nginx 配置优化

# /etc/nginx/nginx.conf
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

数据库性能优化建议：

添加索引

# 查看查询计划
EXPLAIN SELECT * FROM bookmarks WHERE title LIKE '%keyword%';

# 为常用搜索字段添加索引
CREATE INDEX idx_bookmarks_title ON bookmarks(title);
CREATE INDEX idx_bookmarks_url ON bookmarks(url);
CREATE INDEX idx_bookmarks_space_id ON bookmarks(space_id);

# 复合索引
CREATE INDEX idx_bookmarks_space_folder ON bookmarks(space_id, folder_id);

查询优化

# 避免使用 SELECT *
SELECT id, title, url FROM bookmarks WHERE id = ?;

# 使用 LIMIT 限制结果数量
SELECT * FROM bookmarks ORDER BY created_at DESC LIMIT 20;

# 使用分页
SELECT * FROM bookmarks WHERE created_at < ? ORDER BY created_at DESC LIMIT 20;

数据库维护

# 分析表统计信息
ANALYZE;

# 重建索引
REINDEX DATABASE webooks;

# 清理数据库
VACUUM ANALYZE;

账户安全的最佳实践：

强密码策略

• 使用至少 12 位字符的复杂密码
• 包含大小写字母、数字和特殊字符
• 不同网站使用不同密码
• 定期更换密码

双因子认证

• 启用 2FA（如果支持）
• 使用身份验证器应用（如 Google Authenticator）
• 保存备用恢复代码

会话管理

• 定期清除浏览器缓存和 Cookie
• 使用完毕后及时退出登录
• 不要在公共设备上保存密码

监控账户活动

• 定期检查登录历史
• 关注异常登录通知
• 及时更改可疑活动的密码

API 密钥泄露的应急处理：

立即采取的措施

1. 撤销密钥： 在管理后台撤销泄露的 API 密钥
2. 重置密码： 修改相关账户的密码
3. 检查日志： 查看 API 调用日志，确认是否有异常使用
4. 监控账户： 在接下来的几天内密切关注账户活动

生成新密钥

# 生成新的强密钥
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

# 更新 .env 文件
echo "JWT_SECRET=new_generated_secret_here" >> .env

# 重启应用使更改生效
pm2 restart webooks

预防措施

• 限制权限： API 密钥只授予必要权限
• 定期轮换： 每 3-6 个月更换一次密钥
• 环境变量： 永远不要在代码中硬编码密钥
• 访问控制： 限制 API 访问来源

HTTP 错误代码说明：

400 Bad Request

原因： 请求参数错误

解决： 检查请求参数格式和必填字段

# 错误示例
{
  "error": "Invalid request parameters",
  "details": "title is required"
}

401 Unauthorized

原因： 未认证或令牌无效

解决： 检查 JWT 令牌是否有效，重新登录

# 响应示例
{
  "error": "Authentication required",
  "details": "Invalid or expired token"
}

403 Forbidden

原因： 权限不足

解决： 检查用户权限，联系管理员

404 Not Found

原因： 资源不存在

解决： 检查资源 ID 是否正确

500 Internal Server Error

原因： 服务器内部错误

解决： 查看服务器日志，联系技术支持

常见数据库错误及解决方法：

Connection refused

Error: connect ECONNREFUSED 127.0.0.1:5432

# 解决方案：
# 1. 检查 PostgreSQL 服务是否启动
sudo systemctl status postgresql

# 2. 检查端口是否正确
netstat -an | grep 5432

# 3. 检查防火墙设置
sudo ufw status

Database does not exist

Error: database "webooks" does not exist

# 解决方案：
# 1. 创建数据库
createdb webooks

# 2. 或使用 psql
sudo -u postgres createdb webooks

Permission denied

Error: permission denied for table bookmarks

# 解决方案：
# 1. 授权用户访问数据库
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE webooks TO webooks_user;"

# 2. 或修改数据库所有者
sudo -u postgres psql -c "ALTER DATABASE webooks OWNER TO webooks_user;"

Prisma 错误

Error: Prisma Client could not locate the Query Engine for runtime

# 解决方案：
# 1. 重新生成 Prisma 客户端
npx prisma generate

# 2. 检查数据库迁移
npx prisma db push

查看不同类型的日志信息：

应用日志

# 使用 PM2 查看日志
pm2 logs webooks

# 查看实时日志
pm2 logs webooks --lines 100

# 查看错误日志
pm2 logs webooks --err

# 日志文件位置
~/.pm2/logs/

系统日志

# Ubuntu/Debian 系统日志
sudo journalctl -u webooks -f

# 查看特定时间段的日志
sudo journalctl --since "2024-01-01 10:00:00" --until "2024-01-01 11:00:00"

Nginx 日志

# 访问日志
sudo tail -f /var/log/nginx/access.log

# 错误日志
sudo tail -f /var/log/nginx/error.log

数据库日志

# PostgreSQL 日志
sudo tail -f /var/log/postgresql/postgresql-*.log

# 或在 psql 中查看
SELECT * FROM pg_stat_activity;

前端调试技巧：

浏览器开发者工具

• Console： 查看 JavaScript 错误和警告
• Network： 检查 API 请求和响应
• Elements： 检查 DOM 元素和样式
• Application： 查看本地存储和缓存

常见调试命令

# 在浏览器控制台中执行
localStorage.getItem('auth_token')  // 检查认证令牌
console.log('Debug info:', data)    // 输出调试信息
fetch('/api/bookmarks')            // 测试 API 调用

启用调试模式

# 在开发环境中启用详细日志
DEBUG=webooks:* npm run dev

# 或设置环境变量
export DEBUG=webooks:*
npm run dev

多种方式获取帮助：

官方渠道

• 文档： 完整的用户文档和 API 文档
• GitHub Issues： 报告问题和功能请求
• Wiki： 社区维护的指南和教程

社区支持

• 讨论区： 用户交流和互助
• Discord： 实时聊天支持
• Reddit： r/webooks 社区

提交问题时请包含：

• 操作系统和版本
• Node.js 版本
• Webooks 版本
• 详细的错误描述
• 重现步骤
• 相关日志信息

Bug 报告模板：

GitHub Issues 格式

## Bug 描述
简要描述问题

## 重现步骤
1. 打开...
2. 点击...
3. 滚动到...
4. 看到错误

## 预期行为
描述预期会发生什么

## 实际行为
描述实际发生了什么

## 屏幕截图
如果适用，请添加屏幕截图

## 环境信息
- OS: [e.g. Ubuntu 20.04]
- Node.js: [e.g. v18.17.0]
- Webooks: [e.g. v1.2.3]
- 浏览器: [e.g. Chrome 120.0]

## 额外信息
添加任何其他关于问题的信息

欢迎加入 Webooks 社区：

贡献方式

• 代码贡献： 提交 Pull Request
• 文档改进： 完善文档和翻译
• 测试： 帮助测试新功能
• 反馈： 提供使用反馈和建议
• 分享： 向朋友推荐 Webooks

社区资源

• GitHub： https://github.com/yourusername/webooks
• 讨论区： 社区论坛和问答
• 博客： 开发博客和教程
• 视频： YouTube 频道和教程视频

成为贡献者

我们欢迎所有形式的贡献，即使是小的修复也有价值。查看 CONTRIBUTING.md 文件了解详细的贡献指南。

贡献代码的步骤：

1. Fork 项目

在 GitHub 上 Fork 项目到您的账户

2. 克隆代码

git clone https://github.com/yourusername/webooks.git
cd webooks

3. 创建开发分支

git checkout -b feature/your-feature-name

4. 设置开发环境

# 安装依赖
npm install

# 设置环境变量
cp .env.example .env

# 初始化数据库
npx prisma db push

5. 开发和测试

# 启动开发服务器
npm run dev

# 运行测试
npm run test

# 代码检查
npm run lint

6. 提交更改

git add .
git commit -m "feat: add new bookmark feature"
git push origin feature/your-feature-name

7. 创建 Pull Request

在 GitHub 上创建 Pull Request，等待代码审查

请遵循以下编码规范：

代码风格

• 使用 ESLint 和 Prettier 进行代码格式化
• 遵循 TypeScript 严格模式
• 使用有意义的变量和函数名
• 添加必要的注释

提交信息格式

type(scope): description

# 例如：
feat(auth): add JWT token validation
fix(api): resolve bookmarks export issue
docs(readme): update installation guide
test(bookmarks): add unit tests for bookmark service

类型规范

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关