docs: add configuration description and Docker container deployment documentation-agent-runtime-AtomGit

已合并

docs: add configuration description and Docker container deployment documentation #65

陈卉创建于 4月2日从chen-hui-zhe-xi/agent-runtime： add-env-docker-doc 合入到 openJiuwen/agent-runtime： develop

docs: add configuration description and Docker container deployment documentation #65

已合并

陈卉创建于 4月2日

从chen-hui-zhe-xi/agent-runtime add-env-docker-doc合入到openJiuwen/agent-runtime develop

共 2 个文件变更+209-4

Mdocs/zh/2. 配置说明.md+134-1

	@@ -1,2 +1,135 @@
1	-介绍 Runtime 涉及的配置文件、环境变量，说明各配置项的作用以及建议的修改方式。	1	+本文档主要介绍 Runtime 服务部署过程中，核心配置文件 server/.env 的作用、包含的所有环境变量，详细说明各配置项的功能用途，并提供针对性的修改建议，帮助相关运维、开发人员正确配置环境，确保 Runtime 服务（含低码Agent、runtime-server）正常运行。
2		2
		3	+该配置文件为 Runtime 服务的核心环境配置文件，所有环境变量均为服务启动、运行的必要参数，修改时需严格遵循配置规范，避免因参数错误导致服务启动失败或运行异常。以下按配置项分类，逐一说明其作用及修改建议。
		4	+
		5	+# 数据库相关配置
		6	+
		7	+## 数据库通用配置
		8	+
		9	+## DB_TYPE（数据库类型）
		10	+
		11	+作用：定义 Runtime 服务所使用的数据库类型，仅支持 mysql、sqlite 两个可选值，不可填写其他类型，默认配置为 sqlite。
		12	+
		13	+修改建议：根据实际部署的数据库类型修改，若使用 SQLite 数据库，将值改为 sqlite；若使用 MySQL 数据库，将值改为 mysql, 并确保确保数据库服务已正常启动，且与后续数据库配置参数匹配。
		14	+
		15	+## MySQL数据库专用配置
		16	+
		17	+### DB_HOST（MySQL数据库主机地址）
		18	+
		19	+作用：指定MySQL数据库服务所在的主机IP地址或域名，Runtime 服务通过该地址连接数据库。
		20	+
		21	+修改建议：若MySQL数据库部署在远程服务器，需将值改为远程数据库的公网IP地址；若数据库与 Runtime 服务部署在同一服务器，可改为 127.0.0.1或localhost。修改后需确保该地址可被 Runtime 服务所在服务器访问，无防火墙、端口限制。
		22	+
		23	+### DB_PORT（MySQL数据库端口）
		24	+
		25	+作用：指定MySQL数据库服务的监听端口。
		26	+
		27	+修改建议：修改其为MySQL数据库服务的实际监听端口；若使用 SQLite 数据库，该配置项不生效，但也不影响服务运行，但建议注释说明，避免混淆。
		28	+
		29	+### DB_USER（MySQL数据库登录用户名）
		30	+
		31	+作用：指定连接MySQL数据库的用户名，需具备该数据库的读写、创建表等权限，确保 Runtime 服务能正常操作数据库。
		32	+
		33	+修改建议：生产环境中不建议使用 root 账号，建议创建专用数据库账号（如 jiuwen_runtime_user），并分配最小必要权限（仅对 DB_NAME 指定的数据库有操作权限），修改该值为创建的专用账号，提升安全性。
		34	+
		35	+### DB_PASSWORD（MySQL数据库登录密码）
		36	+
		37	+作用：对应 DB_USER 的登录密码，用于验证数据库连接权限，是数据库安全的核心参数。
		38	+
		39	+修改建议：生产环境必须修改，建议设置复杂密码（包含大小写字母、数字、特殊符号，长度不小于8位），避免使用简单密码（如 123456、admin）；密码修改后需同步告知相关运维人员，妥善保管，避免泄露。
		40	+
		41	+### DB_NAME（MySQL目标数据库名称）
		42	+
		43	+作用：指定 Runtime 服务需要连接、操作的数据库名称，服务启动时会自动校验该数据库是否存在（不会自动创建，请自行提前创建）。
		44	+
		45	+修改建议：可根据实际业务需求修改（如 prod_jiuwen_runtime 用于生产环境，test_jiuwen_runtime 用于测试环境）。修改后需确保该数据库已提前创建（服务不支持自动创建），且 DB_USER 账号对该数据库有对应操作权限。
		46	+
		47	+# 服务部署相关配置
		48	+
		49	+此类配置用于指定 Runtime 服务、低码Agent的部署地址、镜像信息及部署目录，直接影响服务的部署效果和运行稳定性。
		50	+
		51	+## IP（服务主机IP地址）
		52	+
		53	+作用：指定 agent-runtime-server 与低码 Agent 组件共同所在的宿主机网络地址。
		54	+
		55	+修改建议：必选项，无默认值。建议填写agent-runtime-server 与低码 Agent 服务实际部署的服务器的有效公网 IP 地址。
		56	+
		57	+## LOWCODE_IMAGE（低码Agent容器镜像地址）
		58	+
		59	+作用：指定低码Agent 容器的镜像地址，当 DEPLOY_TYPE 为 docker 或 k8s 时，服务会根据该地址拉取镜像并启动低码Agent 容器。
		60	+
		61	+修改建议：必选项，无默认值。
		62	+
		63	+## DEPLOY_DIR（部署目录）
		64	+
		65	+作用：指定 Runtime 服务部署过程中产生的所有文件（如配置备份、临时文件等）的存放目录，确保部署文件有序管理。
		66	+
		67	+修改建议：默认值为 /tmp/deploys。建议根据服务器磁盘空间分配情况修改，选择磁盘空间充足、读写速度较快的目录，修改后需确保Runtime 服务运行用户对该目录有读写权限，避免因权限不足导致文件无法生成。
		68	+
		69	+## DIST_DIR（依赖包目录）
		70	+
		71	+作用：指定存放运行低码Agent 所需的所有 .whl 依赖包的目录，服务启动时会从该目录加载依赖包，确保低码Agent 正常运行。
		72	+
		73	+修改建议：默认值为 /tmp/dist。修改后需确保服务运行用户对该目录有读取权限。
		74	+
		75	+# 服务运行相关配置
		76	+
		77	+此类配置用于指定 Runtime 服务的监听地址、端口及启动参数，直接影响服务的可访问性和运行稳定性。
		78	+
		79	+## HOST（服务监听主机）
		80	+
		81	+作用：指定 agent-runtime-server 的监听主机地址，决定哪些网络地址可以访问该服务。
		82	+
		83	+修改建议：默认值为 0.0.0.0，表示允许所有网络地址（内网、公网）访问该服务，适用于生产环境。若仅需内网访问，可修改为服务器内网IP地址（如 192.168.1.100），禁止公网访问，提升服务安全性；不建议修改为 127.0.0.1，否则外部无法访问该服务。
		84	+
		85	+## PORT（服务启动端口号）
		86	+
		87	+作用：指定 agent-runtime-server 的监听端口，外部通过该端口访问服务。
		88	+
		89	+修改建议：默认值为 8186。若该端口被服务器上其他服务占用，需修改为未被占用的端口（建议选择 1024 以上的端口，避免与系统端口冲突）；修改后需同步更新服务访问地址，同时确保该端口已在防火墙中开放，允许外部访问（生产环境需限制访问来源，仅开放给指定IP）。
		90	+
		91	+## UV_EXTRA_ARGS（uv 命令额外参数）
		92	+
		93	+作用：为 uv 命令全局添加额外参数，主要用于解决部分内网、受限环境中，uv pip install 过程中出现的 SSL 证书校验失败、TLS 握手异常、镜像源连接失败等问题，保障依赖包正常安装。
		94	+
		95	+修改建议：提供示例参数 "--native-tls --allow-insecure-host mirrors.aliyun.com -i https://mirrors.aliyun.com/pypi/simple/pip"仅为参考，需根据实际环境修改。
		96	+
		97	+具体修改场景：
		98	+
		99	+- 若环境可正常访问公网镜像源，无需添加镜像源参数；
		100	+
		101	+- 若为内网环境，需将镜像源改为内网私有镜像源（如 "-i https://registry.example.com/pypi/simple/"）；
		102	+
		103	+- 若出现 SSL 证书校验失败，可添加 --allow-insecure-host 指定镜像源主机，或添加 --no-ssl-verify（不建议生产环境使用，存在安全风险）；
		104	+
		105	+- 参数之间需用空格分隔，整体用双引号包裹，避免参数解析错误。
		106	+
		107	+# 服务启动策略配置
		108	+
		109	+此类配置用于指定 runtime-server 的启动方式，决定服务启动时如何启动低码Agent，支持 subprocess、docker、k8s 三种启动策略。
		110	+
		111	+## DEPLOY_TYPE（启动方式配置）
		112	+
		113	+作用：定义 runtime-server 的运行环境及低码Agent 的启动策略，不同值对应不同的部署架构，具体说明如下：
		114	+
		115	+- subprocess（默认值）：runtime-server 以独立进程运行，低码Agent 的类型由部署请求参数动态决定；
		116	+
		117	+- docker：runtime-server 运行在 Docker 环境中，无论部署请求内容如何，仅启动容器版低码Agent，适用于容器化部署场景；
		118	+
		119	+- k8s：runtime-server 运行在 Kubernetes 集群中，无论部署请求内容如何，仅启动 K8s 编排版低码Agent，适用于k8s部署场景。
		120	+
		121	+修改建议：根据实际部署架构修改，修改后需确保运行环境与配置值匹配：
		122	+
		123	+- 进程化部署的runtime-server: 配置 DEPLOY_TYPE=subprocess
		124	+
		125	+- 容器化部署的runtime-server: 配置 DEPLOY_TYPE=docker，同时确保 LOWCODE_IMAGE 配置正确，Docker 服务已正常启动；
		126	+
		127	+- K8s 集群部署的runtime-server: 配置 DEPLOY_TYPE=k8s，同时确保集群环境已配置完成，LOWCODE_IMAGE 配置正确，服务具备 K8s 编排权限。
		128	+
		129	+# 通用修改注意事项
		130	+
		131	+- 所有配置项均为键=值格式，等号前后不可有空格，否则会导致参数解析失败；
		132	+
		133	+- 注释内容以 # 开头，仅用于说明，不影响服务运行，修改时可保留或补充注释，便于后续维护；
		134	+
		135	+- 配置修改后，需重启 runtime-server 服务，修改后的参数才能生效；

Mdocs/zh/3. Agent部署.md+75-3

	@@ -2,10 +2,82 @@
2		2
3	# 进程部署	3	# 进程部署
4		4
5	-
6	-
7	# docker 容器部署	5	# docker 容器部署
8		6
		7	+本文档专门说明 Runtime 服务中，不同部署模式的 runtime-server 启动容器化低码Agent 的具体操作方法，明确操作步骤、配置要求及注意事项，为运维及开发人员提供标准化部署指引。
9		8
		9	+## 进程部署的 runtime-server 启动容器化低码Agent
10		10
11	-# k8s 部署（待开放）	11	+当 runtime-server 以进程模式部署时，可通过以下两种方式启动容器化低码Agent，两种方式可根据实际部署需求灵活选择。
		12	+
		13	+方式一：通过 HTTP 请求指定启动模式
		14	+
		15	+通过发送 HTTP POST 请求，在请求参数中指定 mode=docker，即可触发 runtime-server 启动容器化低码Agent，适用于临时、按需启动容器化Agent的场景。
		16	+
		17	+具体请求命令如下（需根据实际部署环境替换占位参数）：
		18	+
		19	+```
		20	+curl -X POST "http://<runtime-server的IP地址>:<runtime-server的port>/api/v1/agents/deploy?name=<低码agent的名字>&mode=docker" -F "file=@<低码agent的ir.json>"
		21	+```
		22	+
		23	+参数说明：该命令用于触发 runtime-server 按需启动容器化低码Agent，所有尖括号<>包裹的内容为占位参数，需根据实际部署场景替换，具体要求如下：
		24	+
		25	+- <runtime-server的IP地址>：替换为 runtime-server 服务实际部署的主机IP地址（内网/公网均可，需确保请求发起端可访问）；
		26	+
		27	+- <runtime-server的port>：替换为 runtime-server 服务的监听端口（对应 server/.env配置文件中的 PORT 配置项）；
		28	+
		29	+- <低码agent的名字>：替换为自定义的低码Agent名称，建议遵循“业务标识-Agent类型”命名规范，便于区分和管理；
		30	+
		31	+- <低码agent的ir.json>：替换为低码Agent配置文件 ir.json 的本地绝对路径或相对路径，确保发起请求的终端可正常读取该文件，文件格式需符合服务要求。
		32	+
		33	+方式二：通过配置文件固定启动模式
		34	+
		35	+在 runtime-server 对应的配置文件 server/.env 中，将 DEPLOY_TYPE 配置项指定为 docker。配置生效后，无论后续收到何种HTTP部署请求，runtime-server 都会强制启动容器化低码Agent，适用于需统一使用容器化Agent的场景。
		36	+
		37	+核心配置如下：
		38	+
		39	+```
		40	+DEPLOY_TYPE=docker
		41	+```
		42	+
		43	+注意：配置修改后，需重启 runtime-server 进程，确保配置生效。
		44	+
		45	+## 容器部署的 runtime-server 启动容器化低码Agent
		46	+
		47	+当 runtime-server 本身以Docker容器模式部署时，启动容器化低码Agent的操作分为手动启动和一键部署工具启动两种场景，具体操作如下。
		48	+
		49	+场景一：手动启动 runtime-server 容器
		50	+
		51	+若手动执行Docker命令启动 runtime-server 容器，需提前确保配置文件 .env 中已设置DEPLOY_TYPE=docker，同时启动容器时需挂载必要的目录，确保容器内服务可正常调用Docker服务。
		52	+
		53	+具体启动命令如下：
		54	+
		55	+```
		56	+docker run -d --name <studio-runtime-server的容器名> -v <配置文件.env文件路径>:/app/site-packages/openjiuwen_runtime/server/.env -v /var/run/docker.sock:/var/run/docker.sock <studio-runtime-server的镜像名>
		57	+```
		58	+
		59	+说明：
		60	+
		61	+- <studio-runtime-server的容器名> 需替换为实际的容器名称，建议遵循“服务名-环境”的命名规范（如 studio-runtime-server-prod）；
		62	+
		63	+- <配置文件.env文件路径> 需替换为本地 .env 配置文件的绝对路径，确保容器内可读取到正确的配置；并且已设置DEPLOY_TYPE=docker。
		64	+
		65	+- 挂载 /var/run/docker.sock 目录，是为了让容器内的 runtime-server 能够调用宿主机的Docker服务，从而启动低码Agent容器；
		66	+
		67	+- <studio-runtime-server的镜像名> 需替换为实际的 runtime-server 容器镜像地址及标签。
		68	+
		69	+场景二：一键部署工具启动 runtime-server 容器
		70	+
		71	+若通过官方提供的一键部署工具启动 runtime-server 容器，工具会自动完成 DEPLOY_TYPE=docker 配置及相关目录挂载，无需手动进行任何额外操作，启动完成后 runtime-server 会自动按容器化方式启动低码Agent。
		72	+
		73	+## 注意事项
		74	+
		75	+- 无论哪种部署模式，启动容器化低码Agent前，需确保宿主机Docker服务已正常启动，且 runtime-server 具备访问Docker服务的权限；
		76	+
		77	+- 手动启动容器时，务必确保 .env 配置文件挂载路径正确，否则会导致配置读取失败，同时保证已设置DEPLOY_TYPE=docker，无法启动容器化Agent；
		78	+
		79	+- 若启动失败，可优先检查DEPLOY_TYPE 配置、runtime-server 容器的logs，排查相关异常。
		80	+
		81	+- 对于容器化部署的 runtime-server，仅当低码Agent 以容器化方式启动时，低码Agent 才能正常提供服务，非容器化启动方式将导致Agent服务无法响应请求；
		82	+
		83	+# k8s 部署（待开放）