docs: update doc files

Author: YangZxi

README.md

@@ -1,121 +1,163 @@
-# callit
-
+# Callit
+A lightweight self-hosted personal serverless platform based on Docker.  
 轻量级、自建、基于 Docker 的个人 Serverless 平台。
 
+`Callit` 允许你通过 Python 或 Node.js 编写 Worker，并通过 HTTP 路由触发执行，适合轻量 API、HTML 页面展示、个人自动化等服务。
+
+<div style="width: 100%; display: flex; gap: 10px; text-align: center; padding: 20px;">
+  <a href="#快速开始" 
+    style="padding: 8px 14px; background-color: #007bff; color: white; border-radius: 8px; text-decoration: none;"
+    target="_blank" rel="noreferrer">
+      Quick Start
+  </a>
+  <a href="./docs/README.md" 
+    style="padding: 8px 14px; background-color: #e600ff; color: white; border-radius: 8px; text-decoration: none;"
+    target="_blank" rel="noreferrer">
+      Documentation
+  </a>
+</div>
+
+## 屏幕截图
+![Workers Page](./docs/images/workers_page.png)
+![Worker Detail Page](./docs/images/workers_detail_page.png)
+
+## 核心能力
+不依赖 Docker、Kubernetes 等容器技术，提供开箱即用的 Serverless 体验  
+快速开发，支持热更新 Worker 函数  
+
+- 基于 HTTP 路由触发 Worker
+- 支持 Python / Node.js 运行时
+- 支持文件上传、文件返回、HTML 页面返回
+- 支持全局依赖管理
+- 内置 Admin 后台管理 Worker、配置和依赖
+
+tips:
+> 如果你需要一个更成熟、功能更丰富且适用于企业级的 Serverless 平台，应该考虑 OpenFaas、Fission、AWS Lambda、Cloudflare Workers 等解决方案。`Callit` 更适合个人开发者、轻量级使用场景。
+
+## 快速开始
+
+### Docker Compose (推荐)
+
+```yaml
+services:
+  callit:
+    image: yangzxi/callit:latest
+    container_name: callit
+    environment:
+      - ADMIN_TOKEN=   # 在生产环境中请设置一个强随机值
+      # - TZ=Asia/Shanghai
+    ports:
+      - "3100:3100"
+    volumes:
+      - ./data:/app/data
+    restart: unless-stopped
+```
+
+启动：
+
+```bash
+docker compose up -d
+```
+
+启动后可访问：
+
+- Router: `http://127.0.0.1:3100`
+- Admin: `http://127.0.0.1:3100/admin`
+
+## Worker 模板
+
+### Python Worker 模板
+
+```python
+def handler(ctx):
+    request = ctx.get("request", {})
+
+    return {
+        "status": 200,
+        "body": {
+            "message": "Hello, Callit!",
+            "request": request
+        },
+        "headers": {
+            "Content-Type": "application/json"
+        }
+    }
+```
+
+### Node Worker 模板
+
+```javascript
+function handler(ctx) {
+  const { request } = ctx;
+
+  return {
+    status: 200,
+    body: {
+      message: "Hello, Callit!",
+      request,
+    },
+    headers: {
+      "Content-Type": "application/json"
+    }
+  };
+}
+```
+
+说明：
+
+- Worker 目录中必须包含 `main.py` 或 `main.js`
+- 主文件中必须定义 `handler(ctx)`，通过 ctx 对象获取请求信息、上下文等信息
+- 通过返回 JSON 结构化数据来控制 HTTP 响应的状态码、响应体和响应头
+- 具体文档与样例请参考 [Worker 文档](./docs/worker_introduction.md)
+
+
 ## 技术栈
 
 - Backend: Go + Gin
 - Frontend: React + Vite + HeroUI
 - Database: SQLite3
 - Runtime: Python3 / Node.js
 
-## 端口
 
-- Router: `3100`
-- Admin: `3101`
+## 二次开发
+
+如果你需要本地修改源码、调试前端或开发后端，可按下面方式启动。
 
-## 运行前准备
+### 1. 设置管理令牌
 
 ```bash
 export ADMIN_TOKEN=your-token
 ```
 
-## 本地运行
-
-先构建前端并复制到 `/public`：
+### 2. 启动前端
 
 ```bash
 cd pages
-npm run build
-cd ..
-rm -rf public/*
-cp -r pages/dist/* public/
+pnpm install
+pnpm run dev
 ```
 
-再启动后端：
+### 3. 启动后端
 
 ```bash
 go run ./cmd
 ```
 
-## Docker 运行
-
-```bash
-docker compose up --build
-```
+默认前端端口为 `3180`。
+默认后端端口为 `3100`。
 
 ## 数据目录
 
-- `data/app.db`
-- `data/workers/<worker_id>/...`
-- `data/temps/<request_id>/...`（请求结束自动清理）
-- `public`（Admin 前端构建产物目录）
+- `data/app.db`：SQLite 数据库
+- `data/workers/<worker_id>/`：Worker 文件目录
+- `data/temps/<request_id>/`：上传文件临时目录，请求结束后自动清理
+- `data/.lib/<runtime>/`：运行时全局依赖目录
+- `public/`：Admin 前端构建产物目录
 
-## 前端开发
+## 常见使用场景
 
-```bash
-cd pages
-pnpm run dev
-```
-
-默认端口 `3180`，并已将 `/api` 代理到 `http://localhost:3101`。
-
-## 脚本标准输入（stdin）示例
-
-Router 会将请求上下文序列化为 JSON，通过标准输入传给 Worker：
-
-```json
-{
-	"request": {
-		"method": "POST",
-		"uri": "/api/js?data=123&data=456",
-		"url": "http://127.0.0.1:3100/api/js?data=123&data=456",
-		"route_suffix": "/",
-		"params": {
-            // `params` 规则：
-            // - `?data=123` -> `{"data":"123"}`
-            // - `?data=123&data=456` -> `{"data":"456"}`（同名参数以后出现的值覆盖前值）
-			"data": "456"
-		},
-		"headers": {
-			"Content-Type": "application/json",
-			"X-Trace": "abc"
-		},
-		"body": "{\"name\":\"callit\"}",
-		"json": {
-			"name": "callit"
-		}
-	},
-	"event": {
-		"request_id": "f3f3f1f6-8ad0-4f42-b31a-a90f9e8b2b31",
-		"runtime": "node",
-		"worker_id": "2bcf9922-c7d9-4d2e-a15d-b83de4ece1c6",
-		"route": "/api/js"
-	}
-}
-```
-
-## 脚本标准输出（stdout）示例
-
-Worker 必须输出合法 JSON 到标准输出：
-
-```json
-{
-	"status": 200,
-	"headers": {
-		"X-Trace": "abc"
-	},
-	"file": "index.html",
-	"body": {
-		"data": {},
-		"message": "hello"
-	}
-}
-```
-
-说明：
-- `status` 可选，该值决定了 HTTP Status Code，默认 200。
-- `headers` 可选。
-- `body` 为业务响应体，支持 JSON 对象/数组，也支持字符串（例如 HTML 或纯文本）。
-- `file` 可选，表示 Worker 目录下的相对路径（如 `index.html`、`./index.html`、`/index.html`）。
-- 当 `file` 和 `body` 都不存在，固定返回 `404`（忽略 Worker 提供的 `status` 与 `Content-Type`）。
+- 编写 JSON API
+- 上传文件后做解析或处理
+- 生成并返回文件
+- 返回 HTML 页面
+- 使用第三方依赖扩展 Worker 能力

docs/README.md

@@ -0,0 +1,12 @@
+# APP 配置
+[APP 配置](./app_config.md)
+- 包含环境变量配置
+- 包含支持数据库覆盖的 AppConfig 配置项
+- 包含配置优先级说明
+
+# Worker 介绍
+[Worker 介绍](./worker_introduction.md)
+- 包含 Worker 目录结构、`main.xx` 入口要求、`handler(ctx)` 约定
+- 包含 `stdin` / `stdout` / `stderr` 说明
+- 包含上传文件、下载文件、返回 HTML 页面的示例
+  

docs/app_config.md

@@ -0,0 +1,94 @@
+# 程序配置说明
+
+本文档基于 [internal/config/config.go](./internal/config/config.go) 的当前实现整理。
+
+## 配置加载规则
+
+程序配置分为两类：
+
+- 基础运行配置：仅支持环境变量配置，不支持数据库配置。
+- AppConfig：支持环境变量配置，也支持数据库配置覆盖。
+
+其中 AppConfig 的优先级为：
+
+`数据库配置 > 环境变量 > 硬编码默认值`
+
+说明：
+
+- 程序启动时先加载基础运行配置。
+- 随后会加载 AppConfig。
+- 如果数据库中存在对应 key 且 value 非空，则会覆盖环境变量值。
+
+## 基础运行配置
+
+### `ADMIN_TOKEN`
+Admin 接口访问令牌。生产环境必须显式设置为高强度随机值。
+- 必填：是
+- 类型：`string`
+- 默认值：`123123`
+
+### `SERVER_PREFIX`
+Admin 服务访问前缀。程序会自动保证以 `/` 开头，并去掉末尾 `/`。
+- 类型：`string`
+- 默认值：`admin`
+- 说明：如果你希望自定义 `Admin` 后台的访问路径，可以通过设置该环境变量来实现。例如，设置 `SERVER_PREFIX=backend` 后，Admin 后台的访问地址将变为 `http://localhost:3100/backend`。
+
+### `SERVER_PORT`
+程序监听端口，Router 与 Admin 共用该端口。
+- 类型：`int`
+- 默认值：`3100`
+
+### `LOG_LEVEL`
+日志级别。
+- 类型：`string`
+- 默认值：`info`
+
+
+## AppConfig 配置
+
+以下配置项属于 AppConfig 白名单，支持数据库配置。
+
+### `AI_BASE_URL`
+AI 服务基础地址。
+- 类型：`string`
+- 默认值：`https://api.openai.com/v1`
+- 数据库配置：支持数据库配置（数据库的 key: `AI_BASE_URL`）
+
+### `AI_API_KEY`
+AI 服务访问密钥。
+- 类型：`string`
+- 默认值：空字符串
+- 数据库配置：支持数据库配置（数据库的 key: `AI_API_KEY`）
+
+### `AI_MODEL`
+默认使用的 AI 模型名称。
+- 类型：`string`
+- 默认值：`gpt-5`
+- 数据库配置：支持数据库配置（数据库的 key: `AI_MODEL`）
+
+### `AI_MAX_CONTEXT_TOKENS`
+单次对话允许的最大上下文 Token 数。
+- 类型：`int`
+- 默认值：`16000`
+- 数据库配置：支持数据库配置（数据库的 key: `AI_MAX_CONTEXT_TOKENS`）
+
+### `AI_TIMEOUT_MS`
+AI 请求超时时间，单位毫秒。
+- 类型：`int`
+- 默认值：`60000`
+- 数据库配置：支持数据库配置（数据库的 key: `AI_TIMEOUT_MS`）
+
+## 数据库存储说明
+
+支持数据库配置的项会存储在 `app_config` 表中，字段为：
+
+- `key`：配置 key
+- `value`：配置值
+
+当前仅允许写入 AppConfig 白名单中的 key，非白名单配置项不会被接受。
+
+## 补充说明
+
+- 基础运行配置在程序启动时读取，主要用于服务启动、目录定位、数据库初始化等核心能力。
+- AppConfig 主要用于运行中的应用级配置，当前主要是 AI 相关设置。
+- 如果数据库中某个 AppConfig key 存在但值为空，启动同步时不会覆盖环境变量或默认值。