环境变量

Docker Compose 部署使用 asp-compose/ 目录中的 .env。首次执行 init.sh 时，脚本会从 .env.example 创建该文件，并自动生成 Django、PostgreSQL、Redis 和 RustFS 的随机凭据。

修改 .env 后，执行以下命令应用配置：

docker compose up -d
./scripts/doctor.sh

保护 .env

.env 包含服务密码和密钥。请限制文件访问权限，不要提交到代码仓库或发送给无关人员。

镜像

变量	默认值	说明
ASP_BACKEND_IMAGE	当前版本后端镜像	后端、Worker 和迁移服务使用的镜像。
ASP_FRONTEND_IMAGE	当前版本前端镜像	HTTPS 入口和前端页面使用的镜像。

升级脚本会使用最新发布包中的镜像配置更新这两个变量，不需要手工修改。

HTTPS 入口

变量	默认值	说明
ASP_BIND	0.0.0.0	HTTPS 入口在宿主机上的绑定地址。
ASP_HTTPS_PORT	443	HTTPS 入口在宿主机上的端口。
ASP_PUBLIC_HOSTNAME	localhost	仅用于生成备用自签名证书的 CN 和 SAN。
ASP_CERT_EXTRA_SAN	空	自签名证书的额外 SAN，例如 DNS:asp.example.com,IP:10.0.0.10。
ASP_MAX_UPLOAD_SIZE	20m	Nginx 接受的请求体大小上限。

ASP_PUBLIC_HOSTNAME 和 ASP_CERT_EXTRA_SAN 只在 certs/asp.crt 与 certs/asp.key 不存在时生效。正式证书的准备和替换方式见部署。

Web API

变量	默认值	说明
ASP_WEB_WORKERS	3	Gunicorn Worker 进程数。
ASP_WEB_THREADS	4	每个 Worker 的线程数。
ASP_WEB_TIMEOUT	210	请求超时，单位为秒；Nginx 代理超时会基于该值自动计算。
ASP_WEB_KEEPALIVE	5	HTTP keep-alive 时间，单位为秒。
ASP_WEB_MAX_REQUESTS	1000	Worker 处理指定请求数后回收。
ASP_WEB_MAX_REQUESTS_JITTER	100	Worker 回收请求数的随机偏移，避免同时重启。
ASP_DOCTOR_WAIT_SECONDS	180	doctor.sh 等待全部服务就绪的最长时间，单位为秒。

增加 Worker 或线程会提高并发能力，也会增加 CPU、内存和 PostgreSQL 连接消耗。

服务管理界面

变量	默认值	说明
ASP_MANAGEMENT_BIND	0.0.0.0	Redis Stack UI 和 RustFS Console 的宿主机绑定地址。
ASP_REDIS_UI_PORT	8001	Redis Stack UI 的宿主机端口。
ASP_RUSTFS_CONSOLE_PORT	9001	RustFS Console 的宿主机端口。

生产环境应通过防火墙或 VPN 限制管理界面访问。登录方式见服务管理界面。

Django

变量	默认值	说明
DJANGO_SECRET_KEY	初始化时随机生成	Django 加密签名密钥。
DJANGO_DEBUG	false	是否启用 Django Debug。生产环境保持 false。
DJANGO_ALLOWED_HOSTS	*	Django 接受的 Host，多个值使用逗号分隔。
DJANGO_LOG_LEVEL	INFO	应用根日志级别。
DJANGO_LOG_LEVEL_DJANGO	INFO	Django 框架日志级别。
DJANGO_LOG_FORMAT	text	日志格式，可选 text 或 json。

PostgreSQL

连接

变量	默认值	说明
POSTGRES_DB	asp	数据库名称。
POSTGRES_USER	postgres	数据库用户。
POSTGRES_PASSWORD	初始化时随机生成	数据库密码。
POSTGRES_HOST	postgres	后端连接的数据库主机。
POSTGRES_PORT	5432	后端连接的数据库端口。
POSTGRES_CONN_MAX_AGE	60	Django 持久连接生命周期，单位为秒。
POSTGRES_CONN_HEALTH_CHECKS	true	复用持久连接前是否执行健康检查。

服务调优

变量	默认值	说明
POSTGRES_MAX_CONNECTIONS	150	PostgreSQL 最大连接数。
POSTGRES_SHARED_BUFFERS	512MB	PostgreSQL 共享缓冲区。
POSTGRES_EFFECTIVE_CACHE_SIZE	2GB	查询规划器估算的可用缓存，不会直接分配对应内存。
POSTGRES_WORK_MEM	8MB	每个排序或哈希操作可用的内存。
POSTGRES_MAINTENANCE_WORK_MEM	256MB	VACUUM、创建索引等维护操作可用的内存。
POSTGRES_CHECKPOINT_COMPLETION_TARGET	0.9	将 checkpoint 写入分散到检查点周期的比例。
POSTGRES_RANDOM_PAGE_COST	1.1	查询规划器使用的随机页面读取成本。
POSTGRES_LOG_MIN_DURATION_STATEMENT	1000	记录执行时间达到该值的 SQL，单位为毫秒。

PostgreSQL 内存参数会相互叠加。调整前应结合主机内存、并发连接数和实际查询负载评估。

Redis

变量	默认值	说明
REDIS_HOST	redis-stack	后端连接的 Redis 主机。
REDIS_PORT	6379	后端连接的 Redis 端口。
REDIS_DB	1	ASP 使用的 Redis logical database。
REDIS_PASSWORD	初始化时随机生成	Redis 连接密码。

RustFS

变量	默认值	说明
RUSTFS_ENDPOINT_URL	http://rustfs:9000	后端访问 S3-compatible API 的地址。
RUSTFS_ACCESS_KEY	asp	S3-compatible Access Key。
RUSTFS_SECRET_KEY	初始化时随机生成	S3-compatible Secret Key。
RUSTFS_BUCKET	asp	ASP 保存附件和对象的 bucket。
RUSTFS_REGION	us-east-1	S3 请求签名使用的 region。

修改凭据

初始化后不要只修改 .env 中的 PostgreSQL、Redis 或 RustFS 密码。服务端已有凭据不会因此自动更新，可能导致 ASP 无法连接。

如需轮换生产环境凭据，应先在对应服务中完成密码变更，再同步更新 .env 并执行 docker compose up -d。

下一步

• 重启 & 运维 — 应用配置并检查服务状态。
• 服务管理界面 — 登录 Redis Stack UI 和 RustFS Console。
• 备份 & 恢复 — 在重要配置变更前创建全量备份。