# securitymark_openresty

**Repository Path**: composer-liu-ming/securitymark_openresty

## Basic Information

- **Project Name**: securitymark_openresty
- **Description**: 基于openresty实现标识注入
- **Primary Language**: Lua
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenResty 反向代理开发模版

通用 OpenResty 反向代理开发框架，支持 JSON 水印嵌入（键顺序编码）、响应头/响应体修改，开箱即用。

---

## 目录结构

```
securitymark_openresty/
├── shared/                        # 可复用的共享资源
│   ├── mime.types
│   └── lua/
│       ├── watermark.lua          #   JSON 水印嵌入/提取（64位键顺序编码）
│       ├── mark.lua               #   x-mark 安全标记生成（8字段管道格式）
│       ├── store.lua              #   x-mark SQLite 持久化存储
│       ├── analyzer.lua           #   响应体分析器（JSON/HTML 自动识别）
│       ├── header.lua             #   Header 修改工具（增/删/改/条件）
│       ├── body.lua               #   响应体修改工具（追加/替换/JSON变换）
│       ├── utils.lua              #   通用工具函数
│       └── lsqlite3.so            #   SQLite3 Lua C 模块
├── data/                          # 运行时数据（gitignore）
├── proxies/                       # 各个代理项目
│   ├── baidu-mark/                #   百度代理（HTTP 8080 / HTTPS 8445）
│   ├── github-test/               #   GitHub 代理（API 8082/8443 + Web 8084/8444）
│   ├── response-analyzer/         #   响应体分析代理（8081）
│   ├── extract.html               #   水印提取工具（浏览器端）
│   └── (新项目直接在这里加文件夹)
├── template/                      # 新代理项目脚手架
│   ├── nginx.conf
│   └── lua/
│       └── my_handler.lua
└── scripts/
    ├── proxyctl.sh                # 统一管理脚本
    └── setup-deps.sh              # 依赖安装脚本（lsqlite3）
```

---

## 快速开始

### 安装依赖

首次使用前安装 `lsqlite3`（x-mark SQLite 存储需要）：

```bash
cd scripts
./setup-deps.sh
```

### 常用命令

```bash
cd scripts

# 查看所有代理及对应端口、运行状态
./proxyctl.sh status

# 列出所有可用代理
./proxyctl.sh list

# 启动 / 重载 / 停止 / 测试
./proxyctl.sh start   baidu-mark
./proxyctl.sh reload  baidu-mark
./proxyctl.sh stop    baidu-mark
./proxyctl.sh test    baidu-mark
```

### 验证

```bash
# 百度代理 - 搜索建议 API（JSON，带水印）
curl "http://localhost:8080/sugrec?ie=utf-8&prod=pc&wd=test"

# GitHub API 代理 - 用户信息（JSON，带水印）
curl http://localhost:8082/users/google

# 百度代理首页（HTML）
curl -I http://localhost:8080/

# 提取水印：浏览器打开 extract.html 页面
# 粘贴 JSON → 点击「提取水印」
```

---

## 已有代理

| 项目 | HTTP | HTTPS | 目标 | 功能 |
|------|------|-------|------|------|
| `baidu-mark` | 8080 | 8445 | www.baidu.com | 水印 + x-mark |
| `dataflow-mark` | 8099 | — | 222.20.126.197:7999 | x-mark |
| `github-test` | 8082 | 8443 | api.github.com | 水印 |
| `github-test` | 8084 | 8444 | github.com | 水印 |
| `response-analyzer` | 8081 | — | 222.20.126.197:7999 | — |

---

## JSON 水印模块

### 原理

通过阶乘数系统（Lehmer code）将 64 位二进制水印编码为 JSON 对象前 21 个键的排列顺序。不足 21 键时自动从填充池补齐。

### 固定水印

```lua
-- init_by_lua_block
require("watermark").set_watermark("0100100001010101010100110101010001011111001101010011001000110000")
```

`HUST_520` 的 ASCII → 64 位二进制: `H=01001000 U=01010101 S=01010011 T=01010100 _=01011111 5=00110101 2=00110010 0=00110000`

### 随机水印（默认）

不调用 `set_watermark()` 时，每个 worker 首次请求自动生成随机 64 位水印，之后复用。

### 配置示例

推荐使用 `content_by_lua` + `ngx.location.capture()` 模式（支持在响应发出前设置 header）：

```nginx
init_by_lua_block {
    local p = ngx.config.prefix()
    package.path = p .. "../../shared/lua/?.lua;" .. package.path
    require("watermark").set_watermark("你的64位二进制水印")
    require("store").init()
}

server {
    location /upstream/ {
        internal;
        proxy_pass https://目标域名/;
        proxy_ssl_server_name on;
        proxy_set_header Host             目标域名;
        proxy_set_header Accept-Encoding  "";
    }
    location / {
        content_by_lua_block {
            require("my_handler").process()
        }
    }
}
```

> `store.lua` 会自动添加 `lsqlite3.so` 的搜索路径，无需手动配置 `package.cpath`。

具体逻辑在 `lua/my_handler.lua` 中实现（参考 `proxies/baidu-mark/lua/my_handler.lua`）。

### 注意事项

- 上游必须关闭压缩（`proxy_set_header Accept-Encoding "";`），否则 `ngx.location.capture()` 拿到的 body 是压缩后的
- 水印仅对 `Content-Type: application/json` 或 `application/vnd*` 的响应生效
- 如果上游 API 返回 `text/plain` 但内容是 JSON，需在 `my_handler.lua` 中改写 Content-Type（参考 baidu-mark）
- `content_by_lua` 模式会完全缓冲响应体，不适合超大文件或流式接口（SSE）

---

## 共享模块说明

| 模块 | 主要函数 | 推荐时机 | 用途 |
|------|----------|----------|------|
| `watermark.lua` | `.set_watermark()`, `.transform()` | content_by_lua | JSON 水印嵌入 |
| `mark.lua` | `.compute()` | content_by_lua | x-mark 安全标记计算 |
| `store.lua` | `.init()`, `.save()` | init + content_by_lua | x-mark SQLite 持久化 |
| `header.lua` | `.set()`, `.remove_by_pattern()`, `.rename()`, `.set_on_status()`, `.clear_content_length()` | header_filter / content_by_lua | 修改响应头 |
| `analyzer.lua` | `.inspect()` | body_filter | 分析响应体，追加分析元数据 |
| `body.lua` | `.init()`, `.apply()`, `.prepend()`, `.append()`, `.replace_all()`, `.transform_json()` | body_filter + header_filter | 修改响应体 |
| `utils.lua` | `.get_header()`, `.is_content_type()` | 任意阶段 | 通用工具 |

---

## 新增代理项目

推荐使用 `content_by_lua` 模式（支持 x-mark 响应头注入），模板已内置。

```bash
# 1. 复制模板
cp -r template proxies/my-new-proxy

# 2. 修改 nginx.conf — 端口和上游目标
vim proxies/my-new-proxy/nginx.conf
```

`nginx.conf` 中需要改：
- `listen PORT` → 监听端口
- `proxy_pass http://YOUR_TARGET/` → 上游地址
- `proxy_set_header Host YOUR_TARGET` → Host 头
- `init_by_lua_block` — 按需取消注释加载的模块

`lua/my_handler.lua` 中按需取消注释：
- **仅水印** → 取消注释 A) 块
- **仅 x-mark** → 取消注释 B) 块
- **两者都要** → 取消注释 C) 块

```bash
# 3. 启动
./scripts/proxyctl.sh start my-new-proxy

# 4. 如需 HTTPS，走新增 HTTPS 支持流程
```

### 功能速查表

| 想要什么 | 加载的模块 | 操作文件 | 参考项目 |
|----------|-----------|---------|---------|
| JSON 键序水印 | `watermark.lua` | nginx.conf + my_handler A 块 | baidu-mark |
| x-mark 安全标记 + SQLite | `mark.lua` + `store.lua` | nginx.conf + my_handler B 块 | dataflow-mark |
| 水印 + x-mark 都来 | 全加载 | nginx.conf + my_handler C 块 | baidu-mark |
| 无变换纯透传 | 不加载 | 删掉注释，`output = body` 直接返回 | — |

---

## 新增 HTTPS 支持

每个 server 块都需要各自的 `/upstream` 内部 location。

```bash
# 1. 生成自签证书
mkdir -p proxies/my-proxy/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout proxies/my-proxy/ssl/key.pem \
  -out proxies/my-proxy/ssl/cert.pem \
  -subj "/CN=localhost"

# 2. nginx.conf 复制 HTTP server 块，改为 HTTPS:
# server {
#     listen 0.0.0.0:8443 ssl;
#     ssl_certificate     ssl/cert.pem;
#     ssl_certificate_key ssl/key.pem;
#     ssl_protocols       TLSv1.2 TLSv1.3;
#
#     location /upstream/ {
#         internal;
#         proxy_pass https://目标域名/;
#         proxy_ssl_server_name on;
#         ...
#     }
#     location / {
#         content_by_lua_block {
#             require("my_handler").process()
#         }
#     }
# }
```

参考 `proxies/baidu-mark/nginx.conf` 的 HTTP + HTTPS 双 server 配置。

---

## 开发调试

```bash
# 查看运行时日志
tail -f proxies/<name>/logs/error.log

# 在 Lua 中加日志
ngx.log(ngx.ERR, "debug: ", some_var)

# 查看代理状态及端口映射
./scripts/proxyctl.sh status

# 列出所有可用代理
./scripts/proxyctl.sh list

# 测试配置语法
./scripts/proxyctl.sh test <name>
```