Litefs 配置管理文档

Generated by TRAE SOLO at 2026-03-27

概述

Litefs 提供了灵活的配置管理系统，支持多种配置来源和格式，满足不同场景的需求。

配置来源

配置系统支持以下配置来源，按优先级从高到低排列：

代码配置 - 通过代码直接设置配置项
环境变量 - 通过环境变量设置配置（前缀：LITEFS_）
配置文件 - 通过 YAML、JSON 或 TOML 文件设置配置
默认配置 - 系统内置的默认值

配置项

配置项	类型	默认值	说明
`host`	str	`localhost`	服务器监听地址
`port`	int	`9090`	服务器监听端口
`webroot`	str	`./site`	Web 根目录
`debug`	bool	`false`	调试模式
`not_found`	str	`not_found`	404 页面文件名
`default_page`	str	`index`	默认页面文件名
`log`	str	`./default.log`	日志文件路径
`listen`	int	`1024`	服务器监听队列大小
`max_request_size`	int	`10485760`	最大请求体大小（字节，默认 10MB）
`max_upload_size`	int	`52428800`	最大上传文件大小（字节，默认 50MB）
`config_file`	str	`None`	配置文件路径

使用方法

1. 使用默认配置

from litefs import Litefs

app = Litefs()
app.run()

2. 使用代码配置

from litefs import Litefs

app = Litefs(
    host='0.0.0.0',
    port=8080,
    webroot='./site',
    debug=True,
    max_request_size=20971520,
)

app.run()

3. 使用配置文件

YAML 配置文件

创建 litefs.yaml：

host: localhost
port: 9090
webroot: ./site
debug: false
not_found: not_found
default_page: index
log: ./default.log
listen: 1024
max_request_size: 10485760
max_upload_size: 52428800

使用配置文件：

from litefs import Litefs

app = Litefs(config_file='litefs.yaml')
app.run()

JSON 配置文件

创建 litefs.json：

{
  "host": "localhost",
  "port": 9090,
  "webroot": "./site",
  "debug": false,
  "not_found": "not_found",
  "default_page": "index",
  "log": "./default.log",
  "listen": 1024,
  "max_request_size": 10485760,
  "max_upload_size": 52428800
}

使用配置文件：

from litefs import Litefs

app = Litefs(config_file='litefs.json')
app.run()

TOML 配置文件

创建 litefs.toml：

[server]
host = "localhost"
port = 9090
webroot = "./site"
debug = false
listen = 1024

[files]
not_found = "not_found"
default_page = "index"
log = "./default.log"

[limits]
max_request_size = 10485760
max_upload_size = 52428800

使用配置文件：

from litefs import Litefs

app = Litefs(config_file='litefs.toml')
app.run()

4. 使用环境变量

设置环境变量：

export LITEFS_HOST=0.0.0.0
export LITEFS_PORT=8080
export LITEFS_DEBUG=true
export LITEFS_MAX_REQUEST_SIZE=20971520

使用环境变量：

from litefs import Litefs

app = Litefs()
app.run()

5. 混合配置

可以同时使用多种配置来源：

from litefs import Litefs

app = Litefs(
    config_file='litefs.yaml',
    port=8080,
    debug=True,
)

配置优先级：代码配置 > 环境变量 > 配置文件 > 默认值

6. 使用 Config 对象

from litefs import Config

config = Config()

config.update(
    host='0.0.0.0',
    port=8080,
    debug=True,
)

print(config.host)
print(config.port)
print(config.debug)

7. 使用 load_config 函数

from litefs import load_config

config = load_config(
    config_file='litefs.yaml',
    port=8080,
    debug=True,
)

print(config.host)
print(config.port)
print(config.debug)

8. 使用自定义环境变量前缀

from litefs import load_config

config = load_config(
    env_prefix='MYAPP_',
    port=8080,
)

# 现在可以使用 MYAPP_PORT 环境变量

9. 合并多个配置

from litefs import Config, merge_configs

config1 = Config()
config1.update(host='0.0.0.0', port=8080)

config2 = Config()
config2.update(debug=True, port=9090)

merged = merge_configs(config1, config2)

print(merged.host)
print(merged.port)
print(merged.debug)

Config 类 API

构造函数

Config(config_file: Optional[str] = None, **kwargs)

参数：

config_file: 配置文件路径（可选）
**kwargs: 其他配置项

方法

get(key, default=None)

获取配置项。

config = Config()
host = config.get('host', 'default')

set(key, value)

设置配置项。

config = Config()
config.set('host', '0.0.0.0')

update(**kwargs)

批量更新配置。

config = Config()
config.update(
    host='0.0.0.0',
    port=8080,
    debug=True,
)

to_dict()

转换为字典。

config = Config()
config_dict = config.to_dict()

keys()

获取所有配置键。

config = Config()
keys = config.keys()

values()

获取所有配置值。

config = Config()
values = config.values()

items()

获取所有配置项。

config = Config()
items = config.items()

属性访问

支持通过属性访问配置：

config = Config()

host = config.host
port = config.port
debug = config.debug

config.host = '0.0.0.0'
config.port = 8080
config.debug = True

操作符支持

in 操作符

检查配置项是否存在：

config = Config()

if 'host' in config:
    print('host 存在')

命令行参数

Litefs 支持通过命令行参数设置配置：

python -m litefs --host 0.0.0.0 --port 8080 --debug

可用参数：

-H, --host: 服务器监听地址
-P, --port: 服务器监听端口
--webroot: Web 根目录
--debug: 启用调试模式
--not-found: 404 页面文件名
--default-page: 默认页面文件名
--log: 日志文件路径
--listen: 服务器监听队列大小
--max-request-size: 最大请求体大小（字节）
--max-upload-size: 最大上传文件大小（字节）
--config: 配置文件路径

最佳实践

1. 使用配置文件

对于生产环境，建议使用配置文件：

from litefs import Litefs

app = Litefs(config_file='production.yaml')
app.run()

2. 使用环境变量

对于容器化部署，建议使用环境变量：

docker run -e LITEFS_HOST=0.0.0.0 -e LITEFS_PORT=8080 litefs

3. 分层配置

建议使用分层配置：

from litefs import Litefs

app = Litefs(
    config_file='base.yaml',
    port=int(os.getenv('PORT', 9090)),
    debug=os.getenv('DEBUG', 'false').lower() == 'true',
)

4. 配置验证

在使用配置前进行验证：

from litefs import Config

config = Config()

if config.port < 1024 or config.port > 65535:
    raise ValueError('端口号必须在 1024-65535 之间')

if not os.path.exists(config.webroot):
    raise ValueError(f'Web 根目录不存在: {config.webroot}')

5. 配置文件管理

建议为不同环境创建不同的配置文件：

development.yaml - 开发环境
staging.yaml - 测试环境
production.yaml - 生产环境

使用时根据环境选择配置文件：

import os
from litefs import Litefs

env = os.getenv('ENV', 'development')
config_file = f'{env}.yaml'

app = Litefs(config_file=config_file)
app.run()

依赖

YAML 支持

需要安装 PyYAML：

pip install pyyaml

TOML 支持

Python 3.11+ 内置支持 TOML。

Python 3.10 及以下版本需要安装 tomli：

pip install tomli

示例

完整的配置示例请参考：

YAML 配置示例
JSON 配置示例
TOML 配置示例
配置使用示例

Litefs 配置管理文档

概述

配置来源

配置项

使用方法

1. 使用默认配置

2. 使用代码配置

3. 使用配置文件

YAML 配置文件

JSON 配置文件

TOML 配置文件

4. 使用环境变量

5. 混合配置

6. 使用 Config 对象

7. 使用 load_config 函数

8. 使用自定义环境变量前缀

9. 合并多个配置

Config 类 API

构造函数

方法

get(key, default=None)

set(key, value)

update(**kwargs)

to_dict()

keys()

values()

items()

属性访问

操作符支持

in 操作符

命令行参数

最佳实践

1. 使用配置文件

2. 使用环境变量

3. 分层配置

4. 配置验证

5. 配置文件管理

依赖

YAML 支持

TOML 支持

示例

相关文档