webapi
这一页说明内置 Web 配置 API。当前源码里它主要提供 /api/* 配置读写接口,适合配合本地面板或你自己的工具使用。
webapi
yaml
webapi:
enable: false
address: 127.0.0.1:8899
password: ""
tls: false
tlsCertFile: ""
tlsKeyFile: ""
allowOrigins:
- http://127.0.0.1:8899
- http://localhost:8899
- https://127.0.0.1:8899
- https://localhost:8899注意
webapi.enable=true 之后,webapi.password 也必须是非空字符串。当前实现会直接拒绝启动一个“无密码”的管理 API。
webapi.enable
解释
- 这项配置用于启用 koipy 内置的 Web 配置 API 服务。
- 服务会在 bot 启动初始化阶段一起启动,不是单独的外部进程。
- 关闭时,相关监听端口和
/api/*接口都不会启动。
特性
- 类型:
bool - 默认值:
false - 只有在
enable=true且password非空时,服务才会真正监听端口。
配置示例
yaml
webapi:
enable: true
password: "change-this-password"webapi.address
解释
- 这项配置用于指定 API 服务监听地址。
- 当前解析器支持多种写法:
host:port、纯端口号、完整 URL、IPv6 地址(例如[::1]:8899)。 - 如果你写的是完整 URL,它只会被用来提取主机和端口;真正使用
http还是https,仍然由webapi.tls决定。
特性
- 类型:
str - 默认值:
127.0.0.1:8899 - 如果只写
8899,当前实现会自动绑定到127.0.0.1:8899。 - 空值或非法值最终会回退到默认地址。
配置示例
yaml
webapi:
enable: true
address: "[::1]:8899"
password: "change-this-password"webapi.password
解释
- 这是管理 API 的访问密码。
- 当前接口鉴权方式是请求头
X-Access-Password,没有用户名这一层。 /api/health是唯一默认不要求密码的接口,方便做健康检查。
特性
- 类型:
str enable=true时必须非空,否则服务拒绝启动。- 同一IP请求在 60 秒内连续认证失败达到 8 次后,会被临时锁定 300 秒。
- 建议使用强随机密码,不要直接暴露到公网。
- 暴露到公网时请配合反向代理(Nginx、Caddy等)使用,否则后果自负
配置示例
yaml
webapi:
enable: true
password: "a-very-long-random-password"webapi.tls / tlsCertFile / tlsKeyFile
解释
- 这三项用于把管理 API 从
http切到https。 - 当
tls=true时,tlsCertFile必填;tlsKeyFile可选,如果证书文件里已经包含私钥,可以留空。 - 当前实现会把相对路径按
config.yaml所在目录解析,而不是按浏览器当前目录解析。 - 如果证书文件不存在、私钥文件不存在,或 TLS 上下文构建失败,服务会直接启动失败。
特性
- 类型:
bool+str - 默认值:
tls=false、tlsCertFile=""、tlsKeyFile="" address写成https://127.0.0.1:9443本身不会自动开启 TLS,仍然需要tls=true。- 如果你启用了 HTTPS,浏览器端跨域来源也要同步改成
https://...。
配置示例
yaml
webapi:
enable: true
address: "127.0.0.1:9443"
password: "change-this-password"
tls: true
tlsCertFile: "./certs/webapi.pem"
tlsKeyFile: "./certs/webapi.key"webapi.allowOrigins
解释
- 这是浏览器跨域访问时的 CORS 白名单。
- 当前实现按
Origin精确匹配,协议 + 主机 + 端口必须完全一致。 - 如果你把前端页面放到了别的域名、端口,或者把
address改掉了,这里通常也要同步修改。
特性
- 类型:
list[str] - 默认值是 4 个本地回环地址:
127.0.0.1/localhost的http与https版本。 "*"在当前实现里会被直接忽略,并记录一条不安全配置警告。- 它只影响浏览器跨域请求,不影响本机
curl或同源请求。
配置示例
yaml
webapi:
enable: true
address: "127.0.0.1:9443"
password: "change-this-password"
tls: true
tlsCertFile: "./certs/webapi.pem"
tlsKeyFile: "./certs/webapi.key"
allowOrigins:
- "https://127.0.0.1:9443"
- "https://localhost:9443"
- "https://panel.example.com"