Skip to content

Commit 1cda0a5

Browse files
YangZxiYangZxi
committed
docs: update doc files
1 parent 4ceab30 commit 1cda0a5

4 files changed

Lines changed: 787 additions & 87 deletions

File tree

‎README.md‎

Lines changed: 135 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,169 @@
1-
# callit
2-
1+
# Callit
2+
A lightweight self-hosted personal serverless platform based on Docker.
33
轻量级、自建、基于 Docker 的个人 Serverless 平台。
44

5+
`Callit` 允许你通过 Python 或 Node.js 编写 Worker，并通过 HTTP 路由触发执行，适合做轻量 API、文件处理、页面返回和个人自动化服务。
6+
7+
## 核心能力
8+
不依赖 Docker、Kubernetes 等容器技术，提供开箱即用的 Serverless 体验
9+
快速开发，支持热更新 Worker 函数
10+
11+
- 基于 HTTP 路由触发 Worker
12+
- 支持 Python / Node.js 运行时
13+
- 支持文件上传、文件返回、HTML 页面返回
14+
- 支持全局依赖管理
15+
- 内置 Admin 后台管理 Worker、配置和依赖
16+
- [程序配置文档](./docs/app_config.md)
17+
- [Worker 文档](./docs/worker_introduction.md)
18+
19+
tips:
20+
> 如果你需要一个更成熟、功能更丰富且适用于企业级的 Serverless 平台，应该考虑 OpenFaas、Fission、AWS Lambda、Cloudflare Workers 等解决方案。`Callit` 更适合个人开发者、轻量级使用场景。
21+
22+
## 快速开始
23+
24+
### Docker Compose (推荐)
25+
26+
```yaml
27+
services:
28+
callit:
29+
image: yangzxi/callit:latest
30+
container_name: callit
31+
environment:
32+
- ADMIN_TOKEN= # 在生产环境中请设置一个强随机值
33+
# - TZ=Asia/Shanghai
34+
ports:
35+
- "3100:3100"
36+
volumes:
37+
- ./data:/app/data
38+
restart: unless-stopped
39+
```
40+
41+
启动：
42+
43+
```bash
44+
docker compose up -d
45+
```
46+
47+
启动后可访问：
48+
49+
- Router: `http://127.0.0.1:3100`
50+
- Admin: `http://127.0.0.1:3100/admin`
51+
52+
## Worker 模板
53+
54+
### Python Worker 模板
55+
56+
```python
57+
def handler(ctx):
58+
request = ctx.get("request", {})
59+
60+
return {
61+
"status": 200,
62+
"body": {
63+
"message": "Hello, Callit!",
64+
"request": request
65+
},
66+
"headers": {
67+
"Content-Type": "application/json"
68+
}
69+
}
70+
```
71+
72+
### Node Worker 模板
73+
74+
```javascript
75+
function handler(ctx) {
76+
const { request } = ctx;
77+
78+
return {
79+
status: 200,
80+
body: {
81+
message: "Hello, Callit!",
82+
request,
83+
},
84+
headers: {
85+
"Content-Type": "application/json"
86+
}
87+
};
88+
}
89+
```
90+
91+
说明：
92+
93+
- Worker 目录中必须包含 `main.py` 或 `main.js`
94+
- 主文件中必须定义 `handler(ctx)`，通过 ctx 对象获取请求信息、上下文等信息
95+
- 通过返回 JSON 结构化数据来控制 HTTP 响应的状态码、响应体和响应头
96+
- 具体文档与样例请参考 [Worker 文档](./docs/worker_introduction.md)
97+
98+
599
## 技术栈
6100

7101
- Backend: Go + Gin
8102
- Frontend: React + Vite + HeroUI
9103
- Database: SQLite3
10104
- Runtime: Python3 / Node.js
11105

12-
## 端口
13106

14-
- Router: `3100`
15-
- Admin: `3101`
107+
## 二次开发
108+
109+
如果你需要本地修改源码、调试前端或开发后端，可按下面方式启动。
16110

17-
## 运行前准备
111+
### 1. 设置管理令牌
18112

19113
```bash
20114
export ADMIN_TOKEN=your-token
21115
```
22116

23-
## 本地运行
24-
25-
先构建前端并复制到 `/public`：
117+
### 2. 启动前端
26118

27119
```bash
28120
cd pages
29-
npm run build
30-
cd ..
31-
rm -rf public/*
32-
cp -r pages/dist/* public/
121+
pnpm install
122+
pnpm run dev
33123
```
34124

35-
再启动后端：
125+
### 3. 启动后端
36126

37127
```bash
38128
go run ./cmd
39129
```
40130

41-
## Docker 运行
42-
43-
```bash
44-
docker compose up --build
45-
```
131+
默认前端端口为 `3180`。
132+
默认后端端口为 `3100`。
46133

47134
## 数据目录
48135

49-
- `data/app.db`
50-
- `data/workers/<worker_id>/...`
51-
- `data/temps/<request_id>/...`（请求结束自动清理）
52-
- `public`（Admin 前端构建产物目录）
136+
- `data/app.db`：SQLite 数据库
137+
- `data/workers/<worker_id>/`：Worker 文件目录
138+
- `data/temps/<request_id>/`：上传文件临时目录，请求结束后自动清理
139+
- `data/.lib/<runtime>/`：运行时全局依赖目录
140+
- `public/`：Admin 前端构建产物目录
53141

54-
## 前端开发
142+
## 常见使用场景
55143

56-
```bash
57-
cd pages
58-
pnpm run dev
59-
```
144+
- 编写 JSON API
145+
- 上传文件后做解析或处理
146+
- 生成并返回文件
147+
- 返回 HTML 页面
148+
- 使用第三方依赖扩展 Worker 能力
60149

61-
默认端口 `3180`，并已将 `/api` 代理到 `http://localhost:3101`。
62-
63-
## 脚本标准输入（stdin）示例
64-
65-
Router 会将请求上下文序列化为 JSON，通过标准输入传给 Worker：
66-
67-
```json
68-
{
69-
"request": {
70-
"method": "POST",
71-
"uri": "/api/js?data=123&data=456",
72-
"url": "http://127.0.0.1:3100/api/js?data=123&data=456",
73-
"route_suffix": "/",
74-
"params": {
75-
// `params` 规则：
76-
// - `?data=123` -> `{"data":"123"}`
77-
// - `?data=123&data=456` -> `{"data":"456"}`（同名参数以后出现的值覆盖前值）
78-
"data": "456"
79-
},
80-
"headers": {
81-
"Content-Type": "application/json",
82-
"X-Trace": "abc"
83-
},
84-
"body": "{\"name\":\"callit\"}",
85-
"json": {
86-
"name": "callit"
87-
}
88-
},
89-
"event": {
90-
"request_id": "f3f3f1f6-8ad0-4f42-b31a-a90f9e8b2b31",
91-
"runtime": "node",
92-
"worker_id": "2bcf9922-c7d9-4d2e-a15d-b83de4ece1c6",
93-
"route": "/api/js"
94-
}
95-
}
96-
```
150+
相关文档：
97151

98-
## 脚本标准输出（stdout）示例
99-
100-
Worker 必须输出合法 JSON 到标准输出：
101-
102-
```json
103-
{
104-
"status": 200,
105-
"headers": {
106-
"X-Trace": "abc"
107-
},
108-
"file": "index.html",
109-
"body": {
110-
"data": {},
111-
"message": "hello"
112-
}
113-
}
114-
```
152+
- [Worker 文档](./docs/worker_introduction.md)
115153

116-
说明：
117-
- `status` 可选，该值决定了 HTTP Status Code，默认 200。
118-
- `headers` 可选。
119-
- `body` 为业务响应体，支持 JSON 对象/数组，也支持字符串（例如 HTML 或纯文本）。
120-
- `file` 可选，表示 Worker 目录下的相对路径（如 `index.html`、`./index.html`、`/index.html`）。
121-
- 当 `file` 和 `body` 都不存在，固定返回 `404`（忽略 Worker 提供的 `status` 与 `Content-Type`）。
154+
## 文档导航
155+
156+
- [Worker 文档](./docs/worker_introduction.md)
157+
- 包含 Worker 目录结构、`main.xx` 入口要求、`handler(ctx)` 约定
158+
- 包含 `stdin` / `stdout` / `stderr` 说明
159+
- 包含上传文件、下载文件、返回 HTML 页面的示例
160+
- [程序配置文档](./docs/app_config.md)
161+
- 包含环境变量配置
162+
- 包含支持数据库覆盖的 AppConfig 配置项
163+
- 包含配置优先级说明
164+
165+
## 补充说明
166+
167+
- Worker 运行时依赖通过 Admin 后台的 `/dependencies` 页面统一安装
168+
- 依赖安装到 `{DATA_DIR}/.lib/{runtime}` 目录
169+
- 当前 AI 相关配置支持数据库覆盖，详见 [程序配置文档](./docs/app_config.md)

‎docs/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# APP 配置
2+
[APP 配置](./app_config.md)
3+
4+
# Worker 介绍
5+
[Worker 介绍](./worker_introduction.md)

‎docs/app_config.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# 程序配置说明
2+
3+
本文档基于 [internal/config/config.go](./internal/config/config.go) 的当前实现整理。
4+
5+
## 配置加载规则
6+
7+
程序配置分为两类：
8+
9+
- 基础运行配置：仅支持环境变量配置，不支持数据库配置。
10+
- AppConfig：支持环境变量配置，也支持数据库配置覆盖。
11+
12+
其中 AppConfig 的优先级为：
13+
14+
`数据库配置 > 环境变量 > 硬编码默认值`
15+
16+
说明：
17+
18+
- 程序启动时先加载基础运行配置。
19+
- 随后会加载 AppConfig。
20+
- 如果数据库中存在对应 key 且 value 非空，则会覆盖环境变量值。
21+
22+
## 基础运行配置
23+
24+
### `ADMIN_TOKEN`
25+
Admin 接口访问令牌。生产环境必须显式设置为高强度随机值。
26+
- 必填：是
27+
- 类型：`string`
28+
- 默认值：`123123`
29+
30+
### `SERVER_PREFIX`
31+
Admin 服务访问前缀。程序会自动保证以 `/` 开头，并去掉末尾 `/`。
32+
- 类型：`string`
33+
- 默认值：`admin`
34+
- 说明：如果你希望自定义 `Admin` 后台的访问路径，可以通过设置该环境变量来实现。例如，设置 `SERVER_PREFIX=backend` 后，Admin 后台的访问地址将变为 `http://localhost:3100/backend`。
35+
36+
### `SERVER_PORT`
37+
程序监听端口，Router 与 Admin 共用该端口。
38+
- 类型：`int`
39+
- 默认值：`3100`
40+
41+
### `LOG_LEVEL`
42+
日志级别。
43+
- 类型：`string`
44+
- 默认值：`info`
45+
46+
47+
## AppConfig 配置
48+
49+
以下配置项属于 AppConfig 白名单，支持数据库配置。
50+
51+
### `AI_BASE_URL`
52+
AI 服务基础地址。
53+
- 类型：`string`
54+
- 默认值：`https://api.openai.com/v1`
55+
- 数据库配置：支持数据库配置（数据库的 key: `AI_BASE_URL`）
56+
57+
### `AI_API_KEY`
58+
AI 服务访问密钥。
59+
- 类型：`string`
60+
- 默认值：空字符串
61+
- 数据库配置：支持数据库配置（数据库的 key: `AI_API_KEY`）
62+
63+
### `AI_MODEL`
64+
默认使用的 AI 模型名称。
65+
- 类型：`string`
66+
- 默认值：`gpt-5`
67+
- 数据库配置：支持数据库配置（数据库的 key: `AI_MODEL`）
68+
69+
### `AI_MAX_CONTEXT_TOKENS`
70+
单次对话允许的最大上下文 Token 数。
71+
- 类型：`int`
72+
- 默认值：`16000`
73+
- 数据库配置：支持数据库配置（数据库的 key: `AI_MAX_CONTEXT_TOKENS`）
74+
75+
### `AI_TIMEOUT_MS`
76+
AI 请求超时时间，单位毫秒。
77+
- 类型：`int`
78+
- 默认值：`60000`
79+
- 数据库配置：支持数据库配置（数据库的 key: `AI_TIMEOUT_MS`）
80+
81+
## 数据库存储说明
82+
83+
支持数据库配置的项会存储在 `app_config` 表中，字段为：
84+
85+
- `key`：配置 key
86+
- `value`：配置值
87+
88+
当前仅允许写入 AppConfig 白名单中的 key，非白名单配置项不会被接受。
89+
90+
## 补充说明
91+
92+
- 基础运行配置在程序启动时读取，主要用于服务启动、目录定位、数据库初始化等核心能力。
93+
- AppConfig 主要用于运行中的应用级配置，当前主要是 AI 相关设置。
94+
- 如果数据库中某个 AppConfig key 存在但值为空，启动同步时不会覆盖环境变量或默认值。

0 commit comments

Comments
 (0)