WebShare - 专业文本分享平台

WebShare 是一个基于 Node.js 和 Express 构建的专业文本分享平台，允许用户安全地创建、分享和管理文本片段。它支持密码保护分享，并提供简洁的用户界面。

功能特性

• 文本分享: 创建和分享纯文本内容。
• 密码保护: 为分享设置密码，保护敏感信息。
• 静态页面分享: 支持分享 public/views 目录下的静态 HTML 页面。
• 二维码生成: 为每个分享链接生成二维码，方便移动设备访问。
• 平台访问控制: 通过统一的平台密码进行认证。
• 响应式设计: 界面适配不同设备 (基于 public/css/main.css 和模板的通用实践)。
• 安全性:
  • 使用 Helmet 设置安全 HTTP 头。
  • CSRF 保护防止跨站请求伪造。
  • HTML 内容转义防止 XSS。
• Docker 支持: 提供 Dockerfile 和 docker-compose.yml 便于部署。

技术栈

• 后端:
  • Node.js
  • Express.js (Web 框架)
  • EJS (模板引擎)
  • body-parser (请求体解析)
  • express-session (Session 管理)
  • csurf (CSRF 保护)
  • helmet (安全 HTTP 头)
  • compression (Gzip 压缩)
  • winston (日志记录)
  • qrcode (二维码生成)
  • dotenv (环境变量管理)
• 前端:
  • HTML, CSS, JavaScript (具体实现依赖于 public/js/main.js 和 public/css/main.css)
• 数据存储:
  • 文件系统:
    • 文本片段: text_snippets/FILENAME.txt
    • 元数据 (密码等): text_snippets/FILENAME.meta.json
• 开发工具:
  • nodemon (开发时自动重启服务)

项目结构

webshare/
├── config/                     # 应用配置
│   └── config.js               # 主要配置文件 (端口, 密码, 密钥等)
├── controllers/                # 控制器 (业务逻辑处理)
│   ├── authController.js       # 认证逻辑
│   └── shareController.js      # 分享功能逻辑
├── docker-compose.yml          # Docker Compose 配置文件
├── Dockerfile                  # Docker 镜像构建文件
├── optimization_plan.md        # 项目优化计划文档
├── package-lock.json           # 精确依赖版本锁定
├── package.json                # 项目依赖和脚本
├── public/                     # 静态资源
│   ├── css/
│   │   └── main.css            # 主要样式表
│   ├── js/
│   │   └── main.js             # 主要客户端脚本
│   └── views/                  # 静态 HTML 分享页面存放目录
├── routes/                     # 路由定义
│   ├── authRoutes.js           # 认证相关路由
│   └── shareRoutes.js          # 分享相关路由
├── server.js                   # Express 服务器入口文件
├── templates/                  # EJS 模板文件
│   ├── landing.ejs             # 主页
│   ├── layout.ejs              # 全局布局
│   ├── login.ejs               # 登录页
│   ├── share_form.ejs          # 创建/编辑分享表单
│   ├── share_password_prompt.ejs # 分享密码输入提示
│   └── share_view.ejs          # 查看分享内容页
├── text_snippets/              # 存储文本片段和元数据 (动态创建)
└── utils/                      # 工具函数
    └── logger.js               # 日志记录器配置

环境准备与安装

1. Node.js

确保您已安装 Node.js (推荐版本 >= 18.x，与 Dockerfile 一致)。

2. 克隆项目 (如果适用)

git clone <repository_url>
cd webshare

3. 安装依赖

npm install

4. 环境变量配置

项目通过环境变量进行配置。您可以创建一个 .env 文件在项目根目录，或直接设置环境变量。

必要的环境变量:

• PORT: 应用运行的端口 (默认: 3000)。
• PLATFORM_PASSWORD: 访问平台的密码 (生产环境必须设置一个强密码! 默认: yourSecurePlatformPassword123)。
• SESSION_SECRET: 用于 Session 加密的密钥 (生产环境必须设置一个强随机字符串! 默认: anotherSuperStrongRandomSecretKey!@#)。
• NODE_ENV: 应用环境 (development 或 production。默认: development)。

.env.example (推荐创建此文件并加入 .gitignore):

PORT=3000
PLATFORM_PASSWORD=your_actual_strong_password_here
SESSION_SECRET=your_actual_super_random_secret_key_here
NODE_ENV=development

复制以上内容到 .env 文件，并修改为您的实际配置。

运行项目

开发模式

此模式下，nodemon 会在文件更改时自动重启服务器。

npm run dev

应用将运行在 http://localhost:<PORT> (默认 http://localhost:3000)。

生产模式

npm start

或者直接使用 Node:

NODE_ENV=production node server.js

Docker 部署

确保您已安装 Docker 和 Docker Compose。

1. 构建并运行容器:

   docker-compose up -d --build

   这会根据 docker-compose.yml 构建镜像并以后台模式启动服务。 应用将通过 Docker 映射的端口访问 (默认为 http://localhost:32001，根据 docker-compose.yml 配置)。

2. 查看日志:

   docker-compose logs -f share_app

3. 停止服务:

   docker-compose down

核心代码逻辑解析

1. 请求处理流程 (server.js)

• Express 应用初始化。
• 中间件栈:
  • compression(): 响应压缩。
  • helmet(): 设置安全 HTTP 头 (CSP 等)。
  • bodyParser(): 解析请求体。
  • express.static(): 服务静态文件。
  • express-session(): Session 管理。
  • csurf(): CSRF 保护。
  • 自定义中间件: 将 CSRF token, 登录状态等注入 res.locals (server.js)。
  • CSRF 错误处理 (server.js)。
• 动态创建 text_snippets 目录 (server.js)。
• 路由挂载: authRoutes 和 shareRoutes (server.js)。

2. 认证 (controllers/authController.js)

• 登录 (/login):
  • GET: 显示登录页 (authController.getLoginPage)。
  • POST: 验证 PLATFORM_PASSWORD。成功则设置 req.session.isAuthenticated = true (authController.postLogin)。
• 登出 (/logout): 销毁 session (authController.logout)。

3. 分享功能 (controllers/shareController.js)

• 主页 (/):
  • 列出 public/views 下的静态分享和 text_snippets 下的文本分享（包括密码保护状态）(shareController.getHomePage)。
• 创建/编辑分享 (/share/:filename):
  • GET:
    • 编辑模式 (需认证): 显示表单并填充已有内容 (shareController.getSharePage)。
    • 创建模式 (需认证): 显示空表单。
  • POST (需认证):
    • 清理文件名 (shareController.sanitizeFilename)。
    • 保存文本内容到 FILENAME.txt。
    • 保存密码（如果提供）到 FILENAME.meta.json (shareController.postSharePage)。
• 查看分享 (/share/:filename):
  • GET:
    • 如果有密码且未在 session 中验证，提示输入密码。
    • 否则，读取 .txt 文件，转义 HTML (shareController.escapeHtml)，生成二维码，显示内容。
  • POST (用于提交密码):
    • 验证密码，成功则在 session 中记录。
• 删除分享 (/share/:filename/delete) (需认证):
  • 删除对应的 .txt 和 .meta.json 文件 (shareController.deleteShare)。

4. 数据持久化

• 文本片段存储在 text_snippets 目录下的 .txt 文件中。
• 分享的元数据（如密码）存储在同目录下的 .meta.json 文件中。
• 静态分享页面是 public/views 下的子目录，每个子目录被视为一个静态分享。

安全注意事项

• 平台密码和 Session 密钥: 必须在生产环境中更改 config/config.js 或通过环境变量设置强密码和密钥。默认值仅供开发使用。
• CSRF 保护: 已启用，所有表单提交都应包含 CSRF token。
• Helmet: 提供基础的安全 HTTP 头保护。CSP 配置 (server.js) 允许内联脚本，请根据实际需求评估是否需要更严格的策略。
• XSS 防护: 通过 shareController.escapeHtml 对用户提供的文本内容进行转义后显示。
• 文件名处理: shareController.sanitizeFilename 函数用于防止路径遍历等攻击。
• 依赖项安全: 定期运行 npm audit 检查并修复依赖项漏洞。

未来优化方向 (参考 optimization_plan.md)

• 性能:
  • 更积极的静态资源缓存策略。
  • 评估高并发下 .meta.json 文件读写性能，考虑缓存或优化。
• 代码质量:
  • 进一步拆分 server.js 和 shareController.js 中的逻辑到更小的模块/函数。
  • 完善错误处理和用户提示。
  • 增加代码注释。
  • 引入 ESLint/Prettier 统一代码风格。
• 安全性:
  • 确保所有状态更改的 POST 请求都有 CSRF 保护（当前已覆盖大部分）。
  • 根据需要调整 Helmet 的 CSP 策略。
• 文档:
  • 提供更详细的 API 文档（如果适用）。

贡献

欢迎为此项目做出贡献！请遵循以下步骤：

1. Fork 本仓库。
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 打开一个 Pull Request。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件 (如果存在)。