Skip to content

Commit 313f115

Browse files
luoluoyuyuluoluoyuyu
committed
update docs
1 parent 9c18881 commit 313f115

15 files changed

Lines changed: 1260 additions & 19 deletions

‎Makefile‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,10 @@ dist: build
8888
@mkdir -p "$(FULL_PATH)/bin" "$(FULL_PATH)/conf" "$(FULL_PATH)/logs" "$(FULL_PATH)/data/cache/python-runner"
8989
@cp "$(TARGET_DIR)/$(APP_NAME)" "$(FULL_PATH)/bin/"
9090
@cp "$(TARGET_DIR)/cli" "$(FULL_PATH)/bin/"
91-
@cp bin/* "$(FULL_PATH)/bin/"
91+
@cp scripts/start-server.sh scripts/start-cli.sh "$(FULL_PATH)/bin/"
9292
@cp "$(WASM_SOURCE)" "$(FULL_PATH)/data/cache/python-runner/"
9393
@cp conf/config.yaml "$(FULL_PATH)/conf/config.yaml" 2>/dev/null || true
94-
@cp LICENSE README.md "$(FULL_PATH)/" 2>/dev/null || true
94+
@cp LICENSE "$(FULL_PATH)/" 2>/dev/null || true
9595
@printf "Version: $(VERSION)\nBuild: $(ARCH)-$(OS)\nDate: $(DATE)\n" > "$(FULL_PATH)/manifest.txt"
9696
$(call log,ARCHIVE,Compressing to $(DIST_ROOT)/...)
9797
@cd $(DIST_ROOT) && tar -czf "$(FULL_NAME).tar.gz" "$(FULL_NAME)"
@@ -104,9 +104,9 @@ dist-lite: build-lite
104104
@mkdir -p "$(LITE_PATH)/bin" "$(LITE_PATH)/conf" "$(LITE_PATH)/logs" "$(LITE_PATH)/data"
105105
@cp "$(TARGET_DIR)/$(APP_NAME)" "$(LITE_PATH)/bin/"
106106
@cp "$(TARGET_DIR)/cli" "$(LITE_PATH)/bin/"
107-
@cp bin/* "$(LITE_PATH)/bin/"
107+
@cp scripts/start-server.sh scripts/start-cli.sh "$(LITE_PATH)/bin/"
108108
@cp conf/config.yaml "$(LITE_PATH)/conf/config.yaml" 2>/dev/null || true
109-
@cp LICENSE README.md "$(LITE_PATH)/" 2>/dev/null || true
109+
@cp LICENSE "$(LITE_PATH)/" 2>/dev/null || true
110110
@printf "Version: $(VERSION) (Lite)\nBuild: $(ARCH)-$(OS)\nDate: $(DATE)\n" > "$(LITE_PATH)/manifest.txt"
111111
$(call log,ARCHIVE,Compressing to $(DIST_ROOT)/...)
112112
@cd $(DIST_ROOT) && tar -czf "$(LITE_NAME).tar.gz" "$(LITE_NAME)"

‎README-zh.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Function Stream
2+
3+
**Function Stream** 是一个基于 Rust 构建的高性能、事件驱动的流处理框架。它提供了一个模块化的运行时，用于编排编译为 **WebAssembly (WASM)** 的 Serverless 风格处理函数，支持使用 **Go、Python 和 Rust** 编写函数。
4+
5+
## 核心特性
6+
7+
* **事件驱动的 WASM 运行时**：以接近原生的性能和沙箱隔离的方式执行多语言函数（Go、Python、Rust）。
8+
* **持久化状态管理**：内置支持基于 RocksDB 的状态存储，用于有状态流处理。
9+
* **SQL 驱动的 CLI**：使用类 SQL 命令进行作业管理和流检测的交互式 REPL。
10+
11+
## 仓库结构
12+
13+
```text
14+
function-stream/
15+
├── src/ # 核心运行时、协调器、服务器、配置
16+
├── protocol/ # Protocol Buffers 定义
17+
├── cli/ # SQL REPL 客户端
18+
├── conf/ # 默认运行时配置
19+
├── docs/ # 项目文档 (中/英)
20+
├── examples/ # 示例处理器
21+
├── python/ # Python API、客户端和运行时 (WASM)
22+
├── scripts/ # 构建和环境自动化脚本
23+
├── Makefile # 统一构建系统
24+
└── Cargo.toml # 工作区清单
25+
```
26+
27+
## 前置条件
28+
29+
* **Rust 工具链**：Stable >= 1.77 (通过 rustup 安装)。
30+
* **Python 3.9+**：构建 Python WASM 运行时所需。
31+
* **Protoc**：Protocol Buffers 编译器（用于生成 gRPC 绑定）。
32+
* **构建工具**：cmake, pkg-config, OpenSSL headers (用于 rdkafka)。
33+
34+
## 快速开始 (本地开发)
35+
36+
### 1. 初始化环境
37+
38+
我们提供了一个自动化脚本来设置 Python 虚拟环境 (`.venv`)、安装依赖项并编译必要的子模块。
39+
40+
```bash
41+
make env
42+
```
43+
44+
### 2. 构建并运行服务端
45+
46+
以 release 模式启动控制平面。如果缺少 Python WASM 运行时，构建系统将自动编译它。
47+
48+
```bash
49+
cargo run --release --bin function-stream
50+
```
51+
52+
### 3. 运行 CLI
53+
54+
在单独的终端中，启动 SQL REPL：
55+
56+
```bash
57+
cargo run -p function-stream-cli -- --host 127.0.0.1 --port 8080
58+
```
59+
60+
## 构建与打包
61+
62+
项目使用标准的 Makefile 来处理编译和分发。产物生成在 `dist/` 目录中。
63+
64+
### 构建目标
65+
66+
| 命令 | 描述 |
67+
|-------------------|--------------------------------------------------|
68+
| `make` | `make build` 的别名。编译 Rust 二进制文件和 Python WASM 运行时。 |
69+
| `make build` | 构建完整版本（Rust + Python 支持）。 |
70+
| `make build-lite` | 构建精简版本（仅 Rust，无 Python 依赖）。 |
71+
72+
### 分发 (打包)
73+
74+
要创建生产就绪的归档文件（`.tar.gz` 和 `.zip`），请使用 dist 目标。
75+
76+
```bash
77+
make dist
78+
```
79+
80+
**输出：**
81+
* `dist/function-stream-<version>.tar.gz`
82+
* `dist/function-stream-<version>.zip`
83+
84+
对于不包含 Python WASM 运行时的轻量级分发：
85+
86+
```bash
87+
make dist-lite
88+
```
89+
90+
**输出：**
91+
* `dist/function-stream-<version>-lite.tar.gz`
92+
* `dist/function-stream-<version>-lite.zip`
93+
94+
### 运行分发包
95+
96+
解压发布包后，您将看到以下结构：
97+
98+
```text
99+
function-stream-<version>/
100+
├── bin/
101+
│ ├── function-stream # 编译后的二进制文件
102+
│ ├── cli # 编译后的 CLI 二进制文件
103+
│ ├── start-server.sh # 生产环境启动脚本
104+
│ └── start-cli.sh # CLI 启动脚本
105+
├── conf/
106+
│ └── config.yaml # 默认配置
107+
├── data/ # 运行时数据（例如 WASM 缓存）
108+
└── logs/ # 日志目录（运行时创建）
109+
```
110+
111+
### 使用启动脚本 (bin/start-server.sh)
112+
113+
我们提供了一个强大的 Shell 脚本来管理服务器进程，能够处理环境注入、守护进程化和配置覆盖。
114+
115+
**用法：**
116+
117+
```bash
118+
./bin/start-server.sh [选项]
119+
```
120+
121+
**选项：**
122+
123+
| 选项 | 描述 |
124+
|-------------------------|---------------------------------|
125+
| `-d`, `--daemon` | 在后台运行服务器（守护进程模式）。 |
126+
| `-c`, `--config <path>` | 指定自定义配置文件路径。 |
127+
| `-D <KEY>=<VALUE>` | 注入环境变量（例如 `-D RUST_LOG=debug`）。 |
128+
129+
**示例：**
130+
131+
1. **前台模式 (Docker / 调试)** — 在当前 Shell 中运行服务器。适用于容器化环境 (Kubernetes/Docker) 或调试。
132+
133+
```bash
134+
./bin/start-server.sh
135+
```
136+
137+
2. **守护进程模式 (生产)** — 在后台运行服务器，将 stdout/stderr 重定向到 `logs/`。
138+
139+
```bash
140+
./bin/start-server.sh -d
141+
```
142+
143+
3. **自定义配置** — 使用特定配置文件启动。
144+
145+
```bash
146+
./bin/start-server.sh -d -c /etc/function-stream/prod.yaml
147+
```
148+
149+
4. **环境变量注入** — 在不修改脚本或系统 env 的情况下注入环境变量。
150+
151+
```bash
152+
./bin/start-server.sh -d -D RUST_LOG=debug
153+
```
154+
155+
## 维护
156+
157+
| 命令 | 描述 |
158+
|------------------|---------------------------------------------|
159+
| `make clean` | 深度清理。删除 `target/`、`dist/`、`.venv/` 和所有临时产物。 |
160+
| `make env-clean` | 仅删除 Python 虚拟环境和 Python 产物。 |
161+
| `make test` | 运行 Rust 测试套件。 |
162+
163+
## 文档
164+
165+
| 文档 | 描述 |
166+
|------------------------------------------------------|---------------|
167+
| [服务端配置与运维指南](docs/server-configuration-zh.md) | 服务端配置与运维操作 |
168+
| [Function 任务配置规范](docs/function-configuration-zh.md) | 任务定义规范 |
169+
| [SQL CLI 交互式管理指南](docs/sql-cli-guide-zh.md) | 交互式管理指南 |
170+
| [Function 管理与开发指南](docs/function-development-zh.md) | 管理与开发指南 |
171+
| [Python SDK 开发与交互指南](docs/python-sdk-guide-zh.md) | Python SDK 指南 |
172+
173+
## 配置
174+
175+
运行时行为由 `conf/config.yaml` 控制。您可以使用环境变量覆盖配置位置：
176+
177+
```bash
178+
export FUNCTION_STREAM_CONF=/path/to/custom/config.yaml
179+
```
180+
181+
## 许可证
182+
183+
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

‎README.md‎

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ function-stream/
1616
├── protocol/ # Protocol Buffers definitions
1717
├── cli/ # SQL REPL client
1818
├── conf/ # Default runtime configuration
19+
├── docs/ # Documentation (English & Chinese)
1920
├── examples/ # Sample processors
2021
├── python/ # Python API, Client, and Runtime (WASM)
2122
├── scripts/ # Build and environment automation scripts
@@ -62,11 +63,11 @@ The project uses a standard Makefile to handle compilation and distribution. Art
6263

6364
### Build Targets
6465

65-
| Command | Description |
66-
|------------------|------------------------------------------------------------------|
67-
| `make` | Alias for `make build`. Compiles Rust binaries and Python WASM runtime. |
68-
| `make build` | Builds the Full version (Rust + Python Support). |
69-
| `make build-lite`| Builds the Lite version (Rust only, no Python dependencies). |
66+
| Command | Description |
67+
|-------------------|-------------------------------------------------------------------------|
68+
| `make` | Alias for `make build`. Compiles Rust binaries and Python WASM runtime. |
69+
| `make build` | Builds the Full version (Rust + Python Support). |
70+
| `make build-lite` | Builds the Lite version (Rust only, no Python dependencies). |
7071

7172
### Distribution (Packaging)
7273

@@ -98,7 +99,9 @@ After extracting the release package, you will see the following structure:
9899
function-stream-<version>/
99100
├── bin/
100101
│ ├── function-stream # The compiled binary
101-
│ └── start-server.sh # Production startup script
102+
│ ├── cli # The compiled CLI binary
103+
│ ├── start-server.sh # Production startup script
104+
│ └── start-cli.sh # CLI startup script
102105
├── conf/
103106
│ └── config.yaml # Default configuration
104107
├── data/ # Runtime data (e.g. WASM cache)
@@ -117,11 +120,11 @@ We provide a robust shell script to manage the server process, capable of handli
117120

118121
**Options:**
119122

120-
| Option | Description |
121-
|---------------------|-----------------------------------------------------------------------------|
122-
| `-d`, `--daemon` | Run the server in the background (Daemon mode). |
123-
| `-c`, `--config <path>` | Specify a custom configuration file path. |
124-
| `-D <KEY>=<VALUE>` | Inject environment variables (e.g., `-D RUST_LOG=debug`). |
123+
| Option | Description |
124+
|-------------------------|-----------------------------------------------------------|
125+
| `-d`, `--daemon` | Run the server in the background (Daemon mode). |
126+
| `-c`, `--config <path>` | Specify a custom configuration file path. |
127+
| `-D <KEY>=<VALUE>` | Inject environment variables (e.g., `-D RUST_LOG=debug`). |
125128

126129
**Examples:**
127130

@@ -151,11 +154,21 @@ We provide a robust shell script to manage the server process, capable of handli
151154

152155
## Maintenance
153156

154-
| Command | Description |
155-
|------------------|-----------------------------------------------------------------------------|
157+
| Command | Description |
158+
|------------------|--------------------------------------------------------------------------------|
156159
| `make clean` | Deep clean. Removes `target/`, `dist/`, `.venv/`, and all temporary artifacts. |
157-
| `make env-clean` | Removes only the Python virtual environment and Python artifacts. |
158-
| `make test` | Runs the Rust test suite. |
160+
| `make env-clean` | Removes only the Python virtual environment and Python artifacts. |
161+
| `make test` | Runs the Rust test suite. |
162+
163+
## Documentation
164+
165+
| Document | Description |
166+
|----------------------------------------------------------|-----------------------------------|
167+
| [Server Configuration](docs/server-configuration.md) | Server Configuration & Operations |
168+
| [Function Configuration](docs/function-configuration.md) | Task Definition Specification |
169+
| [SQL CLI Guide](docs/sql-cli-guide.md) | Interactive Management Guide |
170+
| [Function Development](docs/function-development.md) | Management & Development Guide |
171+
| [Python SDK Guide](docs/python-sdk-guide.md) | Python SDK Guide |
159172

160173
## Configuration
161174

‎docs/function-configuration-zh.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Function 任务配置规范 (Task Definition)
2+
3+
Function Stream 的任务定义采用插件化架构。虽然当前版本重点支持 Kafka 协议，但其配置模型在设计上支持通过 input-type 与 output-type 扩展至任意流媒体系统。
4+
5+
---
6+
7+
## 一、配置核心结构
8+
9+
| 字段 | 类型 | 必填 | 说明 |
10+
|--------------|--------|----|---------------------------------|
11+
| name | string | 是 | 任务全局唯一标识。 |
12+
| type | string | 是 | 引擎类型：processor (WASM) 或 python。 |
13+
| input-groups | array | 是 | 逻辑输入组。支持将多个物理 Topic 聚合为一个逻辑流。 |
14+
| outputs | array | 是 | 输出目标集合。支持处理结果的多路分发。 |
15+
16+
---
17+
18+
## 二、输入源配置 (input-groups)
19+
20+
系统通过 input-type 标识符动态加载对应的接入插件。
21+
22+
### 2.1 抽象接口参数
23+
24+
| 通用字段 | 说明 |
25+
|------------|------------------------|
26+
| input-type | 驱动类型标识。目前系统内置支持 kafka。 |
27+
28+
### 2.2 Kafka 驱动实现 (当前支持)
29+
30+
当 input-type: kafka 时，需提供以下连接参数：
31+
32+
| 参数 | 必填 | 说明 |
33+
|-------------------|----|---------------------|
34+
| bootstrap_servers | 是 | 集群访问地址。 |
35+
| topic | 是 | 源 Topic。 |
36+
| group_id | 是 | 消费者组 ID。 |
37+
| partition | 否 | 指定分区号，缺省时由集群自动负载均衡。 |
38+
39+
---
40+
41+
## 三、输出目标配置 (outputs)
42+
43+
输出端同样采用插件化设计，允许将同一份处理结果推送到不同的下游生态。
44+
45+
### 3.1 抽象接口参数
46+
47+
| 通用字段 | 说明 |
48+
|-------------|------------------------|
49+
| output-type | 目标驱动标识。目前系统内置支持 kafka。 |
50+
51+
### 3.2 Kafka 驱动实现 (当前支持)
52+
53+
当 output-type: kafka 时，需提供以下参数：
54+
55+
| 参数 | 必填 | 说明 |
56+
|-------------------|----|-------------------------|
57+
| bootstrap_servers | 是 | 目标集群地址。 |
58+
| topic | 是 | 目标 Topic。 |
59+
| partition | 是 | 显式指定写入的分区（由流处理一致性语义要求）。 |

0 commit comments

Comments
 (0)