nsbp-cli 0.2.23 → 0.2.25

package/README.md

@@ -147,7 +147,7 @@ node ./bin/nsbp.js --help  # Test CLI locally
 
 - **Package Name**: `nsbp-cli`
 - **Bin Command**: `nsbp` (install globally and run `nsbp --help`)
-- **Version**: `0.2.23`
+- **Version**: `0.2.25`
 - **Dependencies**: chalk, commander, fs-extra, inquirer
 - **Package Manager**: Uses pnpm (also compatible with npm)
 - **Node Version**: >=16.0.0

package/bin/nsbp.js

@@ -55,19 +55,16 @@ program
         'src',
         'public',
         'scripts',
-        'webpack.base.js',
-        'webpack.client.js', 
-        'webpack.server.js',
+        'config',
+        'docker',
+        'docs',
+        '.env.example',
+        '.env.development',
+        '.env.production',
         'tsconfig.json',
-        'postcss.config.js',
         '.prettierrc',
         '.prettierignore',
         'gitignore',
-        '.dockerignore',
-        'docker-compose.yml',
-        'docker-compose.dev.yml',
-        'Dockerfile',
-        'Dockerfile.dev',
         'Makefile',
         'README.md'
       ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsbp-cli",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "description": "CLI tool for creating NSBP (Node React SSR by Webpack) projects",
   "main": "index.js",
   "homepage": "https://nsbp.erishen.cn/",

package/templates/basic/.env.development

@@ -0,0 +1,13 @@
+# NSBP 开发环境配置
+
+# ==================== 运行环境配置 ====================
+NODE_ENV=development
+PORT=3001
+
+# ==================== 安全配置 ====================
+# 开发环境禁用速率限制（影响开发效率）
+ENABLE_RATE_LIMIT=0
+
+# ==================== 调试配置 ====================
+# 启用详细日志便于调试
+# DEBUG=nsbp:*

package/templates/basic/.env.example

@@ -0,0 +1,33 @@
+# NSBP 环境变量配置
+# 复制此文件为 .env 并根据需要修改配置
+
+# ==================== 运行环境配置 ====================
+NODE_ENV=development
+PORT=3001
+
+# ==================== 安全配置 ====================
+# 启用速率限制（1=启用，0=禁用）
+# 开发环境建议禁用，生产环境建议启用
+ENABLE_RATE_LIMIT=0
+
+# ==================== Docker 配置（Docker 部署时使用）====================
+# Docker 镜像标签（可选）
+# DOCKER_IMAGE_TAG=latest
+
+# ==================== 调试配置 ====================
+# 启用详细日志（开发时有用）
+# DEBUG=nsbp:*
+
+# ==================== 性能配置 ====================
+# 启用性能监控（生产环境可选）
+# ENABLE_PERFORMANCE_MONITORING=0
+
+# ==================== 其他配置 ====================
+# 时区（可选）
+# TZ=Asia/Shanghai
+
+# ==================== 注意事项 ====================
+# 1. 不要将 .env 文件提交到 Git（已在 .gitignore 中忽略）
+# 2. 敏感信息（密钥、密码）请放在 .env.local 中
+# 3. .env.local 不会被提交到 Git，适合存放敏感信息
+# 4. 优先级：.env.local > .env > 默认值

package/templates/basic/.env.production

@@ -0,0 +1,17 @@
+# NSBP 生产环境配置
+
+# ==================== 运行环境配置 ====================
+NODE_ENV=production
+PORT=3001
+
+# ==================== 安全配置 ====================
+# 生产环境启用速率限制（防止 DDoS 和暴力攻击）
+ENABLE_RATE_LIMIT=1
+
+# ==================== 性能配置 ====================
+# 生产环境关闭调试日志
+# DEBUG=
+
+# ==================== 其他配置 ====================
+# 时区
+TZ=Asia/Shanghai

package/templates/basic/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build dev prod down clean logs restart
+.PHONY: help build dev prod down clean logs restart env-dev env-prod env-local
 
 # Package manager detection
 PNPM := $(shell which pnpm)
@@ -19,48 +19,90 @@ help: ## Show this help message
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
 build: ## Build Docker images for production
-	$(COMPOSE) build
+	$(COMPOSE) -f docker/docker-compose.yml build
 
 build-dev: ## Build Docker images for development
-	$(COMPOSE) -f docker-compose.dev.yml build
+	$(COMPOSE) -f docker/docker-compose.dev.yml build
 
 dev: ## Start development environment (removes orphan containers)
-	$(COMPOSE) -f docker-compose.dev.yml up --build --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.dev.yml up --build --remove-orphans
 
 prod: ## Start production environment (removes orphan containers)
-	$(COMPOSE) up -d --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.yml up -d --remove-orphans
 
 down: ## Stop and remove containers (including orphan containers)
-	$(COMPOSE) down --remove-orphans
-	$(COMPOSE) -f docker-compose.dev.yml down --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.yml down --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.dev.yml down --remove-orphans
 
 clean: ## Stop containers, remove images and volumes (including orphan containers)
-	$(COMPOSE) down -v --rmi all --remove-orphans
-	$(COMPOSE) -f docker-compose.dev.yml down -v --rmi all --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.yml down -v --rmi all --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.dev.yml down -v --rmi all --remove-orphans
 
 logs: ## View logs
-	$(COMPOSE) logs -f
+	$(COMPOSE) -f docker/docker-compose.yml logs -f
 
 logs-dev: ## View development logs
-	$(COMPOSE) -f docker-compose.dev.yml logs -f
+	$(COMPOSE) -f docker/docker-compose.dev.yml logs -f
 
 restart: ## Restart production containers
-	$(COMPOSE) restart
+	$(COMPOSE) -f docker/docker-compose.yml restart
 
 restart-dev: ## Restart development containers
-	$(COMPOSE) -f docker-compose.dev.yml restart
+	$(COMPOSE) -f docker/docker-compose.dev.yml restart
 
 rebuild: ## Rebuild and restart production containers (removes orphan containers)
-	$(COMPOSE) up -d --build --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.yml up -d --build --remove-orphans
 
 rebuild-dev: ## Rebuild and restart development containers (removes orphan containers)
-	$(COMPOSE) -f docker-compose.dev.yml up -d --build --remove-orphans
+	$(COMPOSE) -f docker/docker-compose.dev.yml up -d --build --remove-orphans
 
 shell: ## Open shell in production container
-	$(COMPOSE) exec app sh
+	$(COMPOSE) -f docker/docker-compose.yml exec app sh
 
 shell-dev: ## Open shell in development container
-	$(COMPOSE) -f docker-compose.dev.yml exec app sh
+	$(COMPOSE) -f docker/docker-compose.dev.yml exec app sh
 
 test: ## Run tests (if configured)
-	$(COMPOSE) exec app $(PM) test
+	$(COMPOSE) -f docker/docker-compose.yml exec app $(PM) test
+
+env-dev: ## Set up development environment
+	@if [ -f .env.development ]; then \
+		cp .env.development .env && \
+		echo -e "\033[0;32m✅ 开发环境已配置 (.env)\033[0m"; \
+	else \
+		echo -e "\033[0;33m⚠️  .env.development 不存在\033[0m"; \
+	fi
+
+env-prod: ## Set up production environment
+	@if [ -f .env.production ]; then \
+		cp .env.production .env && \
+		echo -e "\033[0;32m✅ 生产环境已配置 (.env)\033[0m"; \
+	else \
+		echo -e "\033[0;33m⚠️  .env.production 不存在\033[0m"; \
+	fi
+
+env-local: ## Set up local environment with sensitive data
+	@if [ ! -f .env.local ]; then \
+		echo "# Local environment (contains sensitive data)" > .env.local && \
+		echo "# DO NOT commit this file to Git" >> .env.local && \
+		echo -e "\033[0;32m✅ .env.local 已创建\033[0m"; \
+		echo "请编辑 .env.local 添加敏感信息"; \
+	else \
+		echo -e "\033[0;33m⚠️  .env.local 已存在\033[0m"; \
+	fi
+
+show-env: ## Show current environment variables
+	@echo "========================================="
+	@echo "当前环境变量配置"
+	@echo "========================================="
+	@echo ""
+	@if [ -f .env ]; then \
+		echo "📄 .env 文件内容："; \
+		cat .env | grep -v "^#" | grep -v "^$$"; \
+	else \
+		echo "⚠️  .env 文件不存在"; \
+	fi
+	@echo ""
+	@if [ -f .env.local ]; then \
+		echo "📄 .env.local 文件存在（包含敏感信息）"; \
+	fi

package/templates/basic/README.md

@@ -2,6 +2,84 @@
 
 🌐 **Online Demo**: [https://nsbp.erishen.cn/](https://nsbp.erishen.cn/)
 
+## 环境变量配置
+
+### 快速开始
+
+```bash
+# 1. 复制环境变量模板
+cp .env.example .env
+
+# 2. 根据需要编辑 .env 文件
+# 编辑 NODE_ENV、PORT、ENABLE_RATE_LIMIT 等
+
+# 3. 开始开发或部署
+pnpm run dev              # 本地开发
+docker-compose up -d         # Docker 部署
+```
+
+### 环境变量说明
+
+| 变量名 | 默认值 | 说明 | 推荐环境 |
+|-------|--------|------|---------|
+| `NODE_ENV` | development | 运行环境 (development/production) | 全部 |
+| `PORT` | 3001 | 服务端口 | 全部 |
+| `ENABLE_RATE_LIMIT` | 0 | 启用速率限制 (1=启用, 0=禁用) | 生产环境 |
+| `DEBUG` | - | 启用调试日志 | 开发环境 |
+| `TZ` | Asia/Shanghai | 时区配置 | 生产环境 |
+
+### 配置文件说明
+
+- **`.env.example`** - 环境变量模板（提交到 Git）
+- **`.env`** - 本地开发配置（不提交到 Git）
+- **`.env.production`** - 生产环境配置（不提交到 Git）
+- **`.env.development`** - 开发环境配置（不提交到 Git）
+- **`.env.local`** - 本地敏感信息（最高优先级，不提交到 Git）
+
+### 配置优先级
+
+```
+.env.local > .env > docker-compose.yml 默认值
+```
+
+### 本地开发配置
+
+```bash
+# 复制开发环境配置
+cp .env.development .env
+
+# 或手动创建 .env 文件
+cat > .env << EOF
+NODE_ENV=development
+PORT=3001
+ENABLE_RATE_LIMIT=0
+EOF
+
+# 启动开发环境
+pnpm run dev
+```
+
+### Docker 部署配置
+
+```bash
+# 生产环境配置
+cp .env.production .env
+
+# Docker Compose 会自动读取 .env 文件
+docker-compose up -d
+
+# 查看环境变量是否生效
+docker-compose exec app env | grep NODE_ENV
+```
+
+### 敏感信息管理
+
+**重要：**
+- ✅ `.env.example` 可以提交到 Git（模板文件）
+- ❌ `.env`、`.env.local` 不要提交到 Git（已在 .gitignore 中）
+- ✅ 敏感信息（密钥、数据库密码）放在 `.env.local` 中
+- ✅ `.env.local` 会覆盖其他配置，优先级最高
+
 ## 开发
 - pnpm run dev   (开发运行)
 - pnpm run build (生产编译)
@@ -141,6 +219,80 @@ make rebuild-dev   # 重新构建并启动开发环境
 
 - `NODE_ENV`: 运行环境 (production/development)
 - `PORT`: 服务端口 (默认 3001)
+- `ENABLE_RATE_LIMIT`: 启用速率限制 (1=启用，0=禁用，默认禁用)
+
+## 安全特性
+
+NSBP 内置了多层安全防护，默认启用生产级安全配置：
+
+### 已启用的安全措施
+
+#### 1. **HTTP 头部安全 (Helmet)**
+- Content Security Policy (CSP): 防止 XSS 攻击
+- X-Frame-Options: 防止点击劫持
+- X-Content-Type-Options: 防止 MIME 类型嗅探
+- Strict-Transport-Security: 强制 HTTPS
+- X-XSS-Protection: XSS 保护
+- Referrer-Policy: 控制引用信息
+
+#### 2. **静态文件安全**
+- ✅ 禁止访问 `.env`、`.git` 等敏感文件
+- ✅ 静态资源缓存优化（1 年缓存）
+- ✅ 请求体大小限制（10MB）
+
+#### 3. **技术栈隐藏**
+- ✅ 移除 `X-Powered-By` 头部
+- ✅ 不暴露 Express 版本信息
+
+#### 4. **速率限制 (可选)**
+- ✅ 15 分钟内最多 100 次请求
+- ✅ 自动限流恶意 IP
+- ✅ 可通过环境变量启用/禁用
+
+### 启用速率限制
+
+在生产环境中，建议启用速率限制以防止 DDoS 攻击：
+
+**Docker 方式：**
+```bash
+# docker-compose.yml 中添加
+environment:
+  - ENABLE_RATE_LIMIT=1
+```
+
+**本地开发方式：**
+```bash
+# .env 文件
+ENABLE_RATE_LIMIT=1
+
+# 或命令行
+ENABLE_RATE_LIMIT=1 pnpm start
+```
+
+### 安全最佳实践
+
+#### 生产环境建议
+1. ✅ **启用 HTTPS**: 使用反向代理（Nginx/Apache）配置 SSL
+2. ✅ **启用速率限制**: 防止暴力攻击和 DDoS
+3. ✅ **设置强密码**: 数据库、API 密钥等
+4. ✅ **定期更新依赖**: `pnpm update`
+5. ✅ **配置防火墙**: 限制入站流量
+
+#### 开发环境
+- ✅ 默认配置已足够
+- ❌ 不建议启用速率限制（影响开发效率）
+- ✅ 保留详细错误日志便于调试
+
+### 安全检查清单
+
+部署前请确认：
+- [ ] 已安装最新依赖 (`pnpm install`)
+- [ ] 环境变量已配置（NODE_ENV=production）
+- [ ] HTTPS 已配置
+- [ ] 敏感信息（密钥、数据库密码）已移出代码库
+- [ ] 速率限制已启用（生产环境）
+- [ ] 静态文件访问已测试
+- [ ] CSP 策略已测试（检查控制台错误）
 
 ### CLI 发布
 

package/templates/basic/{webpack.base.js → config/webpack.base.js}

@@ -2,7 +2,7 @@ const path = require('path')
 const MiniCssExtractPlugin = require('mini-css-extract-plugin')
 const CssMinimizerPlugin = require('css-minimizer-webpack-plugin')
 const TerserPlugin = require('terser-webpack-plugin')
-const { version } = require('./package.json')
+const { version } = require('../package.json')
 const LoadablePlugin = require('@loadable/webpack-plugin')
 const { createLoadableComponentsTransformer } = require('typescript-loadable-components-plugin')
 const BrowserSyncPlugin = require('browser-sync-webpack-plugin')
@@ -54,7 +54,7 @@ module.exports = ({ mode, entry, server, init }) => {
                 logInfoToStdOut: true,
                 logLevel: 'info',
                 transpileOnly: true,
-                configFile: path.resolve(__dirname, './tsconfig.json'),
+                configFile: path.resolve(__dirname, '../tsconfig.json'),
                 getCustomTransformers: (program) => {
                   // console.log('getCustomTransformers', program)
 

package/templates/basic/{webpack.client.js → config/webpack.client.js}

@@ -1,7 +1,7 @@
 const path = require('path') //node的path模块
 const { merge } = require('webpack-merge')
 const config = require('./webpack.base.js')
-const { version } = require('./package.json')
+const { version } = require('../package.json')
 
 const server = false
 
@@ -12,7 +12,7 @@ const entry = {
 const clientConfig = {
   output: {
     //打包出口
-    path: path.resolve(__dirname, 'public'),
+    path: path.resolve(__dirname, '../public'),
     filename: ({ chunk }) => {
       const { name } = chunk
       // console.log('name', name)

package/templates/basic/{webpack.server.js → config/webpack.server.js}

@@ -2,7 +2,7 @@ const path = require('path') //node的path模块
 const nodeExternals = require('webpack-node-externals')
 const { merge } = require('webpack-merge')
 const config = require('./webpack.base.js')
-const { version } = require('./package.json')
+const { version } = require('../package.json')
 
 const init = process.env.INIT || 0
 const server = true
@@ -18,12 +18,12 @@ const serverConfig = {
   output: {
     //打包出口
     filename: `bundle.${version}.js`, //打包后的文件名
-    path: path.resolve(__dirname, 'build'), //存放到根目录的build文件夹
+    path: path.resolve(__dirname, '../build'), //存放到根目录的build文件夹
     clean: true,
     libraryTarget: 'commonjs2'
   },
   externals: [
-    '@loadable/component', 
+    '@loadable/component',
     nodeExternals()
   ] //保持node中require的引用方式
 }

package/templates/basic/{Dockerfile → docker/Dockerfile}

@@ -43,7 +43,7 @@ COPY --from=builder /app/public ./public
 
 # Copy scripts and config
 COPY --from=builder /app/scripts ./scripts
-COPY --from=builder /app/tsconfig.json ./
+COPY --from=builder /app/tsconfig.json ./tsconfig.json
 
 # Change ownership
 RUN chown -R nodejs:nodejs /app

package/templates/basic/{docker-compose.dev.yml → docker/docker-compose.dev.yml}

@@ -1,23 +1,28 @@
+# 从 .env 文件读取环境变量（如果存在）
+# 开发环境配置优先级：.env > docker-compose.dev.yml 默认值
+
 services:
   app:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ..
+      dockerfile: docker/Dockerfile.dev
     container_name: nsbp-app-dev
     ports:
       - "3001:3001"
       - "9229:9229"  # Node.js debug port
     environment:
-      - NODE_ENV=development
-      - PORT=3001
+      - NODE_ENV=${NODE_ENV:-development}
+      - PORT=${PORT:-3001}
+      # 开发环境默认禁用速率限制，如需启用可在 .env 中设置
+      - ENABLE_RATE_LIMIT=${ENABLE_RATE_LIMIT:-0}
     volumes:
       # Mount source code for hot reload
       - ./src:/app/src
       - ./public:/app/public
       - ./scripts:/app/scripts
-      - ./webpack.base.js:/app/webpack.base.js
-      - ./webpack.client.js:/app/webpack.client.js
-      - ./webpack.server.js:/app/webpack.server.js
+      - ./config/webpack.base.js:/app/config/webpack.base.js
+      - ./config/webpack.client.js:/app/config/webpack.client.js
+      - ./config/webpack.server.js:/app/config/webpack.server.js
       - ./tsconfig.json:/app/tsconfig.json
       # Persist node_modules
       - node_modules:/app/node_modules

package/templates/basic/{docker-compose.yml → docker/docker-compose.yml}

@@ -1,14 +1,18 @@
+# 从 .env 文件读取环境变量（如果存在）
+# 生产环境配置优先级：.env > docker-compose.yml 默认值
+
 services:
   app:
     build:
-      context: .
-      dockerfile: Dockerfile
+      context: ..
+      dockerfile: docker/Dockerfile
     container_name: nsbp-app
     ports:
       - "8091:3001"
     environment:
-      - NODE_ENV=production
-      - PORT=3001
+      - NODE_ENV=${NODE_ENV:-production}
+      - PORT=${PORT:-3001}
+      - ENABLE_RATE_LIMIT=${ENABLE_RATE_LIMIT:-1}
     restart: unless-stopped
     healthcheck:
       test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]

package/templates/basic/docs/ENV_CONFIG_GUIDE.md

@@ -0,0 +1,346 @@
+# NSBP 环境变量配置指南
+
+## 快速开始
+
+```bash
+# 1. 复制环境变量模板
+cp .env.example .env
+
+# 2. 根据需要编辑 .env
+nano .env
+
+# 3. 开始开发或部署
+pnpm run dev              # 本地开发
+docker-compose up -d         # Docker 部署
+```
+
+---
+
+## 配置文件说明
+
+### 文件优先级
+
+```
+.env.local (最高优先级) → .env → docker-compose.yml 默认值
+```
+
+### 文件列表
+
+| 文件名 | 说明 | 提交到 Git | 使用场景 |
+|-------|------|-----------|---------|
+| `.env.example` | 环境变量模板 | ✅ 提交 | 新项目初始化 |
+| `.env` | 默认环境配置 | ❌ 不提交 | 日常开发/部署 |
+| `.env.development` | 开发环境配置 | ❌ 不提交 | 切换到开发环境 |
+| `.env.production` | 生产环境配置 | ❌ 不提交 | 切换到生产环境 |
+| `.env.local` | 本地敏感信息 | ❌ 不提交 | 存储密钥、密码等 |
+
+---
+
+## 快速切换环境
+
+### 使用 Makefile（推荐）
+
+```bash
+# 切换到开发环境
+make env-dev
+
+# 切换到生产环境
+make env-prod
+
+# 创建本地配置文件
+make env-local
+
+# 查看当前配置
+make show-env
+```
+
+### 手动方式
+
+```bash
+# 切换到开发环境
+cp .env.development .env
+
+# 切换到生产环境
+cp .env.production .env
+
+# 创建本地配置
+cp .env.example .env.local
+```
+
+---
+
+## 环境变量说明
+
+### 基础配置
+
+```bash
+# 运行环境
+NODE_ENV=development        # 或 production
+
+# 服务端口
+PORT=3001
+
+# 时区
+TZ=Asia/Shanghai
+```
+
+### 安全配置
+
+```bash
+# 启用速率限制
+ENABLE_RATE_LIMIT=1        # 1=启用，0=禁用
+```
+
+**建议：**
+- ✅ 开发环境：`ENABLE_RATE_LIMIT=0`（不影响开发效率）
+- ✅ 生产环境：`ENABLE_RATE_LIMIT=1`（防止 DDoS 攻击）
+
+### 调试配置
+
+```bash
+# 启用详细日志
+DEBUG=nsbp:*
+```
+
+---
+
+## 使用场景
+
+### 场景 1：新项目初始化
+
+```bash
+# 1. 克隆项目
+git clone <repository-url>
+cd nsbp
+
+# 2. 复制环境变量模板
+cp .env.example .env
+
+# 3. 安装依赖
+pnpm install
+
+# 4. 启动开发环境
+pnpm run dev
+```
+
+### 场景 2：日常开发
+
+```bash
+# 使用开发环境配置
+make env-dev
+
+# 启动开发环境
+pnpm run dev
+```
+
+### 场景 3：Docker 部署
+
+```bash
+# 切换到生产环境
+make env-prod
+
+# 启动 Docker 容器
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+```
+
+### 场景 4：敏感信息管理
+
+```bash
+# 1. 创建本地配置文件
+make env-local
+
+# 2. 编辑 .env.local 添加敏感信息
+nano .env.local
+
+# 添加内容：
+# DATABASE_URL=postgresql://user:pass@localhost:5432/db
+# API_SECRET=your-secret-key
+# JWT_SECRET=jwt-secret-key
+
+# .env.local 会自动覆盖 .env 中的同名变量
+```
+
+---
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **始终使用 .env 文件**
+   ```bash
+   # 不要在代码中硬编码
+   const PORT = process.env.PORT || 3001  # ✅
+   const PORT = 3001  # ❌
+   ```
+
+2. **分离敏感信息**
+   ```bash
+   # .env - 非敏感配置（可以分享给团队）
+   NODE_ENV=development
+   PORT=3001
+   ENABLE_RATE_LIMIT=0
+
+   # .env.local - 敏感配置（个人使用）
+   DATABASE_URL=postgresql://localhost/db
+   API_KEY=secret-key-123
+   ```
+
+3. **提供 .env.example**
+   ```bash
+   # .env.example - 示例配置（提交到 Git）
+   NODE_ENV=development
+   PORT=3001
+   ENABLE_RATE_LIMIT=0
+   # API_KEY=your-api-key  # 提供示例，不包含真实值
+   ```
+
+4. **使用环境前缀**
+   ```bash
+   # 命名规范
+   NSBP_NODE_ENV=development
+   NSBP_PORT=3001
+   NSBP_ENABLE_RATE_LIMIT=0
+   ```
+
+### ❌ 避免做法
+
+1. **不要提交 .env 到 Git**
+   ```bash
+   # .gitignore 已包含
+   .env
+   .env.local
+   .env.*.local
+   ```
+
+2. **不要在代码中硬编码敏感信息**
+   ```javascript
+   // ❌ 错误做法
+   const dbPassword = "my-password-123"
+   
+   // ✅ 正确做法
+   const dbPassword = process.env.DB_PASSWORD
+   ```
+
+3. **不要在 .env.example 中包含真实值**
+   ```bash
+   # .env.example - 只提供示例
+   API_KEY=your-api-key-here  # ✅
+   API_KEY=sk-1234567890abcdef  # ❌
+   ```
+
+---
+
+## Docker Compose 集成
+
+### 自动读取 .env
+
+Docker Compose 会自动读取项目根目录下的 `.env` 文件：
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    environment:
+      - NODE_ENV=${NODE_ENV:-production}
+      - PORT=${PORT:-3001}
+      - ENABLE_RATE_LIMIT=${ENABLE_RATE_LIMIT:-1}
+```
+
+### 使用方式
+
+```bash
+# 1. 创建 .env 文件
+cp .env.production .env
+
+# 2. Docker Compose 自动读取
+docker-compose up -d
+
+# 3. 验证环境变量
+docker-compose exec app env | grep NODE_ENV
+```
+
+---
+
+## 故障排除
+
+### 问题 1：环境变量未生效
+
+**检查步骤：**
+```bash
+# 1. 检查 .env 文件是否存在
+ls -la .env
+
+# 2. 查看文件内容
+cat .env
+
+# 3. 验证格式（等号两边不要有空格）
+NODE_ENV=development  # ✅
+NODE_ENV = development  # ❌
+
+# 4. 重启服务
+docker-compose restart
+```
+
+### 问题 2：敏感信息泄露
+
+**预防措施：**
+```bash
+# 1. 检查 .gitignore
+cat .gitignore | grep .env
+
+# 2. 验证文件未被提交
+git ls-files | grep .env
+
+# 3. 如果已提交，从历史记录中移除
+git filter-branch --force --index-filter \
+  'git rm --cached --ignore-unmatch .env'
+```
+
+### 问题 3：环境变量优先级混乱
+
+**验证方法：**
+```bash
+# 1. 显示容器中的环境变量
+docker-compose exec app env | sort
+
+# 2. 查看实际生效的值
+docker-compose exec app sh -c 'echo $NODE_ENV'
+
+# 3. 检查 .env.local 是否覆盖了预期值
+cat .env.local | grep NODE_ENV
+```
+
+---
+
+## 常用命令速查
+
+```bash
+# 查看当前配置
+make show-env
+
+# 切换开发环境
+make env-dev
+
+# 切换生产环境
+make env-prod
+
+# 创建本地配置
+make env-local
+
+# 查看容器环境变量
+docker-compose exec app env
+
+# 验证特定变量
+docker-compose exec app sh -c 'echo $ENABLE_RATE_LIMIT'
+```
+
+---
+
+## 参考资源
+
+- [Docker Compose 环境变量](https://docs.docker.com/compose/environment-variables/)
+- [Node.js process.env](https://nodejs.org/api/process.html#process_process_env)
+- [十二因子应用](https://12factor.net/)

package/templates/basic/docs/QUICKSTART.md

@@ -0,0 +1,99 @@
+# Docker 快速启动指南
+
+🌐 **Online Demo**: [https://nsbp.erishen.cn/](https://nsbp.erishen.cn/)
+
+## 5 分钟快速开始
+
+### 生产环境（推荐用于生产部署）
+
+```bash
+# 1. 构建并启动
+docker-compose up -d
+
+# 2. 查看状态
+docker-compose ps
+
+# 3. 查看日志（可选）
+docker-compose logs -f
+
+# 4. 访问应用
+open http://localhost:3001
+```
+
+完成！🎉
+
+### 开发环境（推荐用于开发）
+
+```bash
+# 1. 构建并启动（前台运行，可查看构建日志）
+docker-compose -f docker-compose.dev.yml up --build
+
+# 2. 等待看到 "Server listening on port 3001"
+# （首次启动需要 1-3 分钟进行构建）
+
+# 3. 访问应用
+open http://localhost:3001
+
+# 4. 修改代码，自动热重载
+```
+
+**提示：** 如果想在后台运行：
+```bash
+docker-compose -f docker-compose.dev.yml up -d --build
+docker-compose -f docker-compose.dev.yml logs -f
+```
+
+## 常用命令
+
+### 生产环境
+```bash
+make prod         # 启动
+make logs         # 查看日志
+make restart      # 重启
+make down         # 停止
+make clean        # 完全清理
+```
+
+### 开发环境
+```bash
+make dev          # 启动（带热重载）
+make logs-dev     # 查看日志
+make restart-dev   # 重启
+```
+
+### 通用
+```bash
+make help         # 查看所有命令
+make shell        # 进入生产容器
+make shell-dev    # 进入开发容器
+```
+
+## 验证安装
+
+检查 Docker 是否正确安装：
+```bash
+docker --version
+docker-compose --version
+```
+
+测试配置：
+```bash
+./scripts/verify-dev.sh
+```
+
+## 遇到问题？
+
+- 查看 README.md 中的 Docker 部署章节
+- 运行 `./scripts/verify-dev.sh` 验证开发环境状态
+- 确保 Docker 守护进程正在运行
+
+## 目录说明
+
+- `Dockerfile` - 生产环境镜像
+- `Dockerfile.dev` - 开发环境镜像
+- `docker-compose.yml` - 生产环境配置
+- `docker-compose.dev.yml` - 开发环境配置
+- `Makefile` - 快捷命令
+- `scripts/verify-dev.sh` - 开发环境验证脚本
+- `README.md` - 完整文档
+- `QUICKSTART.md` - 本文档

package/templates/basic/gitignore

@@ -23,6 +23,8 @@ public/*.json
 .env
 .env.local
 .env.*.local
+.env.development
+.env.production
 
 # Logs
 logs

package/templates/basic/package.json

@@ -3,16 +3,16 @@
   "version": "1.0.0",
   "description": "node react ssr by webpack",
   "main": "index.js",
-  "homepage": "https://nsbp.erishen.cn/",
+  "homepage": "https://nsbp.erishen.cn",
   "scripts": {
     "dev": "npm-run-all -l -s dev:init -p dev:build:*",
-    "dev:init": "cross-env INIT=1 webpack --config webpack.server.js --mode development",
-    "dev:build:server": "webpack --config webpack.server.js --mode development --watch",
-    "dev:build:client": "webpack --config webpack.client.js --mode development --watch",
+    "dev:init": "cross-env INIT=1 webpack --config config/webpack.server.js --mode development",
+    "dev:build:server": "webpack --config config/webpack.server.js --mode development --watch",
+    "dev:build:client": "webpack --config config/webpack.client.js --mode development --watch",
     "dev:build:start": "node ./scripts/start.js",
     "build": "pnpm run clean && npm-run-all -l -p build:**",
-    "build:server": "webpack --config webpack.server.js --mode production",
-    "build:client": "webpack --config webpack.client.js --mode production",
+    "build:server": "webpack --config config/webpack.server.js --mode production",
+    "build:client": "webpack --config config/webpack.client.js --mode production",
     "start": "node ./scripts/start.js",
     "clean": "rimraf build && rimraf public/js && rimraf public/css && rimraf public/client.* && rimraf public/*.js && rimraf public/*.js.map && rimraf public/*.txt && rimraf public/*.json && rimraf .temp_cache",
     "format": "prettier --write **/*.{js,css,less,scss,ts,tsx}",
@@ -37,7 +37,9 @@
     "@reduxjs/toolkit": "^2.11.2",
     "axios": "^1.7.0",
     "express": "^5.2.1",
+    "express-rate-limit": "^8.2.0",
     "framer-motion": "^12.25.0",
+    "helmet": "^8.1.0",
     "lodash": "^4.17.21",
     "probe-image-size": "^7.1.0",
     "react": "^19.2.3",

package/templates/basic/public/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+    <linearGradient id="gradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#2563eb" />
+      <stop offset="100%" stop-color="#1d4ed8" />
+    </linearGradient>
+  </defs>
+  <rect width="100" height="100" rx="20" fill="url(#gradient)" />
+  <text x="50" y="68" font-family="Arial, sans-serif" font-size="60" font-weight="bold" text-anchor="middle" fill="white">N</text>
+</svg>

package/templates/basic/public/site.webmanifest

@@ -0,0 +1,20 @@
+{
+  "name": "Nsbp.js - 轻量级 React SSR 框架",
+  "short_name": "Nsbp.js",
+  "description": "轻量级 React SSR 框架，专为低资源部署与高度可定制场景而生",
+  "icons": [
+    {
+      "src": "/favicon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/favicon-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#2563eb",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

package/templates/basic/scripts/verify-dev.sh

@@ -20,7 +20,7 @@ else
     echo ""
     echo "启动命令："
     echo "  make dev"
-    echo "  docker-compose -f docker-compose.dev.yml up -d --build"
+    echo "  docker-compose -f docker/docker-compose.dev.yml up -d --build"
     exit 1
 fi
 
@@ -35,7 +35,7 @@ fi
 
 echo ""
 echo "3. 检查权限错误..."
-if docker-compose -f docker-compose.dev.yml logs 2>&1 | grep -q "EACCES"; then
+if docker-compose -f docker/docker-compose.dev.yml logs 2>&1 | grep -q "EACCES"; then
     echo -e "${RED}❌ 发现权限错误${NC}"
     echo ""
     echo "最近的权限错误："
@@ -46,7 +46,7 @@ fi
 
 echo ""
 echo "4. 检查构建状态..."
-if docker-compose -f docker-compose.dev.yml logs 2>&1 | grep -q "compiled successfully"; then
+if docker-compose -f docker/docker-compose.dev.yml logs 2>&1 | grep -q "compiled successfully"; then
     echo -e "${GREEN}✅ 构建完成${NC}"
 else
     echo -e "${YELLOW}⚠️  构建中或未开始${NC}"
@@ -54,7 +54,7 @@ fi
 
 echo ""
 echo "5. 检查服务器监听..."
-if docker-compose -f docker-compose.dev.yml logs 2>&1 | grep -q "listening"; then
+if docker-compose -f docker/docker-compose.dev.yml logs 2>&1 | grep -q "listening"; then
     echo -e "${GREEN}✅ 服务器正在监听${NC}"
 else
     echo -e "${YELLOW}⚠️  服务器尚未启动监听${NC}"
@@ -69,9 +69,9 @@ echo "访问应用："
 echo "  http://localhost:3001"
 echo ""
 echo "查看日志："
-echo "  docker-compose -f docker-compose.dev.yml logs -f"
+echo "  docker-compose -f docker/docker-compose.dev.yml logs -f"
 echo ""
 echo "停止服务："
 echo "  make down"
-echo "  docker-compose -f docker-compose.dev.yml down"
+echo "  docker-compose -f docker/docker-compose.dev.yml down"
 echo ""

package/templates/basic/scripts/verify-security.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+
+echo "========================================="
+echo "NSBP 安全功能验证"
+echo "========================================="
+echo ""
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# 检查依赖
+echo "1. 检查安全依赖安装..."
+if grep -q '"helmet"' package.json && grep -q '"express-rate-limit"' package.json; then
+    echo -e "${GREEN}✅ helmet 和 express-rate-limit 已安装${NC}"
+else
+    echo -e "${RED}❌ 缺少安全依赖${NC}"
+    exit 1
+fi
+
+echo ""
+
+# 检查服务器代码
+echo "2. 检查服务器代码安全配置..."
+if grep -q "helmet(" src/server/index.ts; then
+    echo -e "${GREEN}✅ Helmet 已启用${NC}"
+else
+    echo -e "${RED}❌ Helmet 未配置${NC}"
+fi
+
+if grep -q "rateLimit" src/server/index.ts; then
+    echo -e "${GREEN}✅ 速率限制已配置（可选）${NC}"
+else
+    echo -e "${RED}❌ 速率限制未配置${NC}"
+fi
+
+if grep -q "dotfiles: 'ignore'" src/server/index.ts; then
+    echo -e "${GREEN}✅ dotfiles 访问已禁用${NC}"
+else
+    echo -e "${RED}⚠️  dotfiles 配置需要检查${NC}"
+fi
+
+if grep -q "disable('x-powered-by')" src/server/index.ts; then
+    echo -e "${GREEN}✅ X-Powered-By 已隐藏${NC}"
+else
+    echo -e "${RED}❌ X-Powered-By 未隐藏${NC}"
+fi
+
+if grep -q "express.json.*limit" src/server/index.ts && grep -q "express.urlencoded.*limit" src/server/index.ts; then
+    echo -e "${GREEN}✅ 请求体大小限制已配置${NC}"
+else
+    echo -e "${RED}❌ 请求体大小限制未配置${NC}"
+fi
+
+echo ""
+
+# 检查 CSP 配置
+echo "3. 检查 Content Security Policy..."
+if grep -q "contentSecurityPolicy" src/server/index.ts; then
+    echo -e "${GREEN}✅ CSP 已配置${NC}"
+    if grep -q "defaultSrc.*'self'" src/server/index.ts; then
+        echo -e "${GREEN}   - default-src: 'self'${NC}"
+    fi
+    if grep -q "scriptSrc" src/server/index.ts; then
+        echo -e "${GREEN}   - script-src 已配置${NC}"
+    fi
+    if grep -q "styleSrc" src/server/index.ts; then
+        echo -e "${GREEN}   - style-src 已配置${NC}"
+    fi
+    if grep -q "imgSrc.*https:" src/server/index.ts; then
+        echo -e "${GREEN}   - img-src 允许 HTTPS${NC}"
+    fi
+else
+    echo -e "${RED}❌ CSP 未配置${NC}"
+fi
+
+echo ""
+
+# 检查文档
+echo "4. 检查安全文档..."
+if grep -q "## 安全特性" README.md; then
+    echo -e "${GREEN}✅ 安全章节已添加到 README${NC}"
+else
+    echo -e "${YELLOW}⚠️  建议添加安全章节到 README${NC}"
+fi
+
+echo ""
+
+# 统计
+echo "========================================="
+echo "安全配置统计"
+echo "========================================="
+
+TOTAL_CHECKS=7
+PASSED_CHECKS=0
+
+# 统计通过项
+grep -q '"helmet"' package.json && grep -q '"express-rate-limit"' package.json && ((PASSED_CHECKS++))
+grep -q "helmet(" src/server/index.ts && ((PASSED_CHECKS++))
+grep -q "dotfiles: 'ignore'" src/server/index.ts && ((PASSED_CHECKS++))
+grep -q "disable('x-powered-by')" src/server/index.ts && ((PASSED_CHECKS++))
+grep -q "express.json.*limit" src/server/index.ts && ((PASSED_CHECKS++))
+grep -q "contentSecurityPolicy" src/server/index.ts && ((PASSED_CHECKS++))
+grep -q "## 安全特性" README.md && ((PASSED_CHECKS++))
+
+SCORE=$(( PASSED_CHECKS * 100 / TOTAL_CHECKS ))
+
+echo -e "通过率: ${PASSED_CHECKS}/${TOTAL_CHECKS} (${YELLOW}${SCORE}%${NC})"
+echo ""
+
+if [ $SCORE -eq 100 ]; then
+    echo -e "${GREEN}🎉 所有安全检查通过！${NC}"
+    echo "项目已达到生产级安全标准。"
+elif [ $SCORE -ge 70 ]; then
+    echo -e "${YELLOW}✅ 安全配置良好${NC}"
+    echo "建议检查未通过的项目。"
+else
+    echo -e "${RED}⚠️  安全配置需要改进${NC}"
+    echo "请检查上述未通过的项目。"
+fi
+
+echo ""
+echo "========================================="

package/templates/basic/src/server/index.ts

@@ -1,12 +1,62 @@
 import express from 'express'
+import helmet from 'helmet'
+import rateLimit from 'express-rate-limit'
 import { render } from './utils'
 import { getPhotoWH, getPhotoMenu } from './photo'
 import { useCurrentFlag, outPhotoDicPath } from '../utils/config'
 
 const app = express()
 
-app.use(express.static('public', { dotfiles: 'allow' }))
-!useCurrentFlag && app.use(express.static(outPhotoDicPath, { dotfiles: 'allow' }))
+// 1. Security headers (helmet)
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:", "https:"],
+      connectSrc: ["'self'", "https:"],
+      fontSrc: ["'self'", "data:"],
+      objectSrc: ["'none'"],
+      mediaSrc: ["'self'"],
+      frameSrc: ["'none'"],
+    },
+  },
+  crossOriginEmbedderPolicy: false, // Allow inline scripts for SSR
+  crossOriginOpenerPolicy: false, // Allow window.open for development
+}))
+
+// 2. Hide X-Powered-By header
+app.disable('x-powered-by')
+
+// 3. Rate limiting (optional, controlled by environment variable)
+if (process.env.ENABLE_RATE_LIMIT === '1') {
+  const limiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100, // Limit each IP to 100 requests per windowMs
+    message: 'Too many requests from this IP, please try again later.',
+    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
+    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+  })
+  app.use('/api', limiter)
+  console.log('🛡️ Rate limiting enabled for /api routes')
+}
+
+// 4. Static file serving (disable dotfiles access)
+app.use(express.static('public', { 
+  dotfiles: 'ignore',
+  setHeaders: (res, filePath) => {
+    // Cache static assets for 1 year
+    if (filePath.match(/\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/)) {
+      res.setHeader('Cache-Control', 'public, max-age=31536000, immutable')
+    }
+  }
+}))
+!useCurrentFlag && app.use(express.static(outPhotoDicPath, { dotfiles: 'ignore' }))
+
+// 5. Body parsing with size limits
+app.use(express.json({ limit: '10mb' }))
+app.use(express.urlencoded({ limit: '10mb', extended: true }))
 
 //使用express提供的static中间件,中间件会将所有静态文件的路由指向public文件夹
 
@@ -27,4 +77,8 @@ app.use((req, res) => {
 const PORT = process.env.PORT || 3001
 app.listen(PORT, () => {
   console.log(`Server listening on port ${PORT}`)
+  console.log(`🔒 Security headers enabled`)
+  if (process.env.ENABLE_RATE_LIMIT === '1') {
+    console.log(`🚦 Rate limiting active`)
+  }
 })

package/templates/basic/src/server/utils.tsx

@@ -116,6 +116,13 @@ export const render = (req: any, res: any) => {
               <html>
                   <head>
                       <meta charset="utf-8">
+                      <link rel="icon" type="image/x-icon" href="/favicon.ico">
+                      <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+                      <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+                      <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
+                      <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
+                      <link rel="manifest" href="/site.webmanifest">
+                      <meta name="theme-color" content="#2563eb">
                       ${helmet?.title?.toString()}
                       ${helmet?.meta?.toString()}
                       ${styleTags}