一、项目定位与核心价值

djevops 是一款面向 Django 应用的命令行部署工具，旨在帮助开发者将 Django Web 应用一键部署到运行 Ubuntu 或 Debian 的 Linux VPS（虚拟专用服务器）上。它不依赖 Docker，而是直接在服务器上以原生进程的方式管理数据库、Redis、Nginx、Postfix 等组件，从而显著缩短"推送上线"的时间。

根据 README.md 的描述，djevops 的核心价值体现在以下几点：

• 非容器化部署：避免 Docker 引入的额外抽象层与性能开销，实现秒级上线 README.md:1-10。
• Ansible 的精简替代品：djevops 专注于 Django 场景，相比通用配置管理工具，所需的配置代码量显著更少 README.md:9-11。
• 安全默认值：每个服务以独立用户运行，进程间环境变量不会泄漏；默认不开放非预期端口，例如 Postfix 场景下会自动屏蔽 25 端口的外部访问 README.md。
• 自动运维：内置操作系统自动更新、日志轮转压缩、数据库持续备份（基于 Litestream）等能力 README.md。

二、整体架构概览

djevops 在客户端与服务器端协同工作：客户端负责生成配置与传输文件，服务器端通过"组件注册表"按需安装与卸载底层依赖。

flowchart LR
    A[本地开发机<br/>执行 djevops CLI] -->|rsync djevops.yml<br/>+ secrets.json| B[远程服务器<br/>root@VPS]
    A -->|SSH| B
    B --> C[ComponentRegistry<br/>组件注册表]
    C --> D[AptPackage<br/>系统包]
    C --> E[ServiceUser<br/>服务用户]
    C --> F[NginxSite<br/>反向代理]
    C --> G[VirtualEnvironment<br/>Python venv]
    C --> H[Litestream / Postfix<br/>数据库与邮件]
    C --> I[TemplatedFile / Crontab<br/>配置与定时任务]
    G --> J[/srv/app<br/>Django 应用]
    J --> K[Gunicorn<br/>WSGI 服务]

如架构图所示，djevops 客户端通过 SSH 将 djevops.yml（部署配置）和 secrets.json（密钥字典）上传到服务器的 /root/.djevops/ 状态目录，再调用服务器端的 python -m djevops.remote.deploy 触发安装流程 djevops/__main__.py:142-162。服务器端的 ComponentRegistry 会记录每个组件的安装参数，确保重复部署时跳过已安装项，必要时卸载不再被声明的组件 djevops/remote/component_registry.py:6-19。

三、快速入门步骤

3.1 环境准备

• 在本地开发机通过 pip install djevops 安装 CLI。
• 准备一台拥有 SSH root 权限的 Linux VPS，操作系统要求为 Ubuntu 或 Debian README.md:12-18。
• 在 Django 项目根目录初始化 Git 仓库并添加远程仓库，否则 djevops init 会报错 djevops/__main__.py:67-72。

3.2 初始化项目（init）

在 Django 仓库根目录执行 djevops init，CLI 会自动：

1. 校验 .git 目录与 manage.py 是否存在 djevops/__main__.py:67-79。
2. 通过 _get_declared_dependencies() 函数读取依赖列表。最新版本同时支持 pyproject.toml 的 [project.dependencies] 与 requirements.txt 两种声明方式，这是社区近期关注的重要改进 djevops/__main__.py:108-126。
3. 校验依赖中必须包含 django 与 gunicorn djevops/__main__.py:79-83。
4. 自动从 Git 远程地址解析服务器地址与分支，写入 deploy/djevops.yml djevops/__main__.py:84-104。
5. 生成 deploy/secrets.py 模板，便于集中管理敏感信息 djevops/__main__.py:106-110。

3.3 配置与密钥

生成的 deploy/djevops.yml 是声明式配置文件，支持 server、git、services、db、mail、redis 等顶层节点；密钥则统一写入 deploy/secrets.py，通过本地求值后上传为 JSON 常量，从而避免直接提交到 Git djevops/__main__.py:24-43。常见做法是在 secrets.py 中通过 os.environ['MY_SECRET'] 读取本地环境变量。

3.4 部署（deploy）与远程命令

执行 djevops deploy 时，CLI 会调用 deploy() 函数：先用 check_config() 进行本地校验，再通过 SSH 在服务器上安装 djevops 自身，然后 rsync 推送配置文件并最终调用 python -u -m djevops.remote.deploy djevops/__main__.py:142-162。

此外，CLI 还提供以下常用子命令：

四、常见前置检查与故障提示

djevops 会在多个阶段进行"失败即终止"的校验，错误信息会附带 GIT_HINT 提示，提醒开发者提交并推送变更 djevops/__init__.py:1。常见的检查包括：

• settings.ALLOWED_HOSTS 必须包含域名或 IP，且格式受支持，否则会被 check_django_settings.py 拒绝 djevops/check_django_settings.py:6-16。
• SQLite 模式下，settings.DATABASES['default']['NAME'] 必须等于环境变量 SQLITE_DB_FILE 的值 djevops/check_django_settings.py:36-43。
• PostgreSQL 模式下，数据库引擎必须是 django.db.backends.postgresql djevops/check_django_settings.py:23-30。
• 远程部署时，本地与服务器端通过 SshKey 组件注册 SSH 密钥，并通过 KnownHostsEntry 预置 Git 主机的指纹，避免首次拉取时的交互确认 djevops/remote/deploy.py:36-44。

服务器侧的运行时支持也较为完善，例如 actions.py 暴露了 migrate_db、collect_static_files、get_django_setting 等便捷操作，可在远程 deploy 流程中调用 manage.py 子命令 djevops/remote/actions.py:1-20；util.py 则提供 SSH、apt-get、域名校验等通用工具 djevops/util.py。

五、See Also

• 数据库与备份配置（基于 Litestream 与 PostgreSQL）
• 服务与组件管理：Celery、Redis、Nginx
• 密钥管理与 secrets.py 最佳实践

概述

djevops 是一个面向 Django 应用的部署命令行工具，它通过一份声明式 YAML 配置文件 deploy/djevops.yml 来描述目标服务器、Git 仓库、服务、数据库、邮件与 Redis 等组件，并配合一份 Python 形式的密钥文件 deploy/secrets.py 提供敏感数据。配置信息会在本地被解析后上传到服务器的 /root/.djevops/ 目录下，分别保存为 deploy.yml、secrets.json 和 components.json，供部署与运行时使用（README.md、djevops/remote/scaffold.py:5-19）。

社区中最常被讨论的需求是「依赖从哪里声明」与「密钥如何安全传入」。最新版本已支持 requirements.txt，用户既可以使用现代的 pyproject.toml，也可以沿用传统的 requirements.txt（djevops/__main__.py:_get_declared_dependencies）。

djevops.yml 的结构

djevops init 命令会基于当前 Git 仓库与远端地址生成一份最小可用的配置样例。生成的 deploy/djevops.yml 形如：

server: 0.0.0.0
git:
  repo: githubuser/mydjangoapp
  branch: main
services:
  web:
    type: django

该样例由 init() 中的 deploy_yml 字典组装得到，其中 server 默认使用 SAMPLE_SERVER_IP = '0.0.0.0'（djevops/__main__.py:SAMPLE_SERVER_IP）。下面是顶层配置项的速查：

若缺少 services.web，CLI 会以 CommandError 提示用户添加至少一个 django 类型服务（djevops/__main__.py:init/deploy）。db.type 必须在 sqlite 与 postgres 之间二选一，否则同样抛出错误（djevops/__main__.py）。

初始化流程

下图展示了 djevops init 在本地生成配置和密钥文件的关键流程：

flowchart TD
    A[执行 djevops init] --> B{存在 .git?}
    B -- 否 --> X1[报错: 非 Git 仓库]
    B -- 是 --> C{存在 Git remote?}
    C -- 否 --> X2[报错: 缺少 remote]
    C -- 是 --> D{存在 manage.py?}
    D -- 否 --> X3[报错: 缺少 manage.py]
    D -- 是 --> E[读取 pyproject.toml 或 requirements.txt]
    E --> F[写入 deploy/djevops.yml]
    F --> G[写入 deploy/secrets.py 样例]
    G --> H[提示运行 djevops deploy]

关键约束包括：必须在 Git 仓库中、必须配置过至少一个 remote、必须存在 manage.py，并要求本地已声明依赖（djevops/__main__.py:init）。依赖项既可以写在 pyproject.toml 的 [project.dependencies]，也可以写在 requirements.txt 中（djevops/__main__.py:_get_declared_dependencies）。

密钥管理：deploy/secrets.py

deploy/secrets.py 是一个普通的 Python 文件，它会在本地被 runpy.run_path 执行，并把执行结果作为环境常量上传到服务器。这种方式使密钥可以来自任意 Python 表达式，包括硬编码、读取 os.environ、调用密码管理器等。SAMPLE_SECRETS_PY 中给出的推荐写法是：

import os
MY_SECRET = os.environ['MY_SECRET']
DJANGO_SECRET_KEY = '...'

变量名需匹配正则 SECRETS_NAME_RE = r'^[A-Z][A-Z0-9_]+$'，以便在 YAML 中清晰引用。部署时 get_services_users_envs 会把密钥合并进每个服务的环境变量中，从而避免明文密钥进入 Git 历史（djevops/__main__.py:SAMPLE_SECRETS_PY、README.md）。

服务器端的密钥文件最终落地为 JSON：部署完成后，/root/.djevops/secrets.json 由 get_secrets() 读取；部署配置由 get_deploy_config() 从 /root/.djevops/deploy.yml 解析；组件状态则保存在 components.json，由 ComponentRegistry 用来判断哪些组件需要安装、卸载或复用（djevops/remote/scaffold.py:5-37、djevops/remote/component_registry.py）。

数据库与备份配置

db.backup 子段是声明式备份的核心入口。sqlite 类型会通过 get_litestream_config 生成 Litestream 的 replica 配置：

db:
  type: sqlite
  backup:
    type: s3
    bucket: mybackup
    access-key-id: S3_BACKUP_ACCESS_KEY
    secret-access-key: S3_BACKUP_SECRET_KEY
    path: db
    region: us-east-1

若使用 postgres，则由 djevops/remote/postgres.py 通过 pg_dump 与 cron 周期执行备份；周期字符串需同时能被 parse_sync_interval 解析并能用 as_cron 转换为 cron 表达式，否则抛出 CommandError（djevops/__main__.py、djevops/litestream.py、djevops/remote/postgres.py）。

常见校验与失败模式

在执行 deploy 之前，本地 CLI 会调用 check_django_settings.py 校验 Django settings.py。例如 ALLOWED_HOSTS 中如果出现既非域名又非 IP 的条目，会打印错误并通过 GIT_HINT 提示用户提交推送；DATABASES['default']['NAME'] 必须等于环境变量 SQLITE_DB_FILE 的值（djevops/check_django_settings.py、djevops/__init__.py:GIT_HINT）。util.is_domain 与 is_ip 用于辅助判断 ALLOWED_HOSTS 合法性（djevops/util.py）。

See Also

• README.md — 部署示例与功能总览
• djevops/remote/deploy.py — 部署主流程
• djevops/remote/components.py — 可复用组件基类
• djevops/remote/actions.py — Django 管理命令封装

djevops 是一套面向 Django 应用的部署命令行工具，采用"本地编排 + 远端执行"的双端架构：本地负责解析 deploy/djevops.yml 与 deploy/secrets.py、组装配置并通过 SSH/RSync 将其上传；远端则由一组声明式"组件"在服务器上落实具体变更。其核心思想是 *不可变声明 + 幂等应用*——每次运行都把服务器当作目标态去收敛，而不是编写过程式脚本。资料来源：djevops/__main__.py:42-87、README.md

总体架构与执行流

部署流程由 djevops CLI 启动入口 main() 分发命令。init 用于生成 deploy/djevops.yml 与 deploy/secrets.py 模板；deploy 负责把本地配置推送到服务器并触发远端脚本 python -u -m djevops.remote.deploy 实施变更。资料来源：djevops/__main__.py:53-58

sequenceDiagram
    participant Dev as 开发者本地
    participant CLI as djevops CLI
    participant Server as 远程服务器
    participant Reg as ComponentRegistry
    Dev->>CLI: djevops deploy
    CLI->>CLI: load_config() 校验 yml + secrets.py
    CLI->>Server: rsync djevops.yml → /root/.djevops/deploy.yml
    CLI->>Server: rsync secrets.json → /root/.djevops/secrets.json
    CLI->>Server: ssh python -m djevops.remote.deploy
    Server->>Reg: require(AptPackage/ServiceUser/...)
    Reg->>Server: install() / save_components()
    Server-->>Dev: 部署完成日志

状态文件与脚手架

服务器侧的"事实来源"由三个文件构成，集中存放在 STATE_DIR = /root/.djevops：

资料来源：djevops/remote/scaffold.py:5-37

secrets.py 在本地通过 runpy.run_path 执行后再上传，因此可以安全地使用 os.environ、密码管理器等动态来源，服务器侧只看到 JSON 常量。资料来源：djevops/__main__.py:128-150

组件系统与注册表

djevops 远端的所有"做事的单元"都派生自抽象基类 Component，例如 AptPackage、ServiceUser、NginxSite、LetsEncryptCertificate、Litestream、Postfix、TemplatedFile 等。ComponentRegistry 负责协调它们的安装/卸载：

• require(component)：以 ClassName[:key] 为唯一键检查持久化记录 components.json。若参数完全一致则跳过；否则调用 component.install() 并写回文件。资料来源：djevops/remote/component_registry.py:7-30
• uninstall_unused()：在部署结束时反向遍历 components.json，对已不再被 require 的组件执行 uninstall()，并按"删一条存一次"的方式写回，以避免中断运行后留下脏数据。资料来源：djevops/remote/component_registry.py:32-46

这种设计天然支持*增量部署*与*自动清理*：用户在 djevops.yml 中删除某项服务，下次部署即可回收相应资源。

远端部署主流程

djevops/remote/deploy.py 的 main() 是远端编排核心，其典型步骤包括：

1. 读取 deploy.yml 与 secrets.json，并解析 git 段（server、repo、branch、key）。资料来源：djevops/remote/deploy.py:32-45
2. 依据是否存在 git_repo_key 选择 HTTPS 或 SSH 拉取方式；如有 SSH 私钥则通过 require(SshKey(...)) 安装并配置 KnownHostsEntry。资料来源：djevops/remote/deploy.py:47-58
3. 通过 git fetch + reset --hard origin/<branch> 更新 /srv/app；失败时回退到 git clone。资料来源：djevops/remote/deploy.py:60-72
4. 注册 ServiceUser、VirtualEnvironment、TemplatedFile（Nginx、systemd 单元等）、IptablesRules、Hostname、Postfix、Litestream 等组件并调用 install()。
5. 最后调用 registry.uninstall_unused() 回收残留组件。

Django 特有的副作用——如 migrate_db、collect_static_files、install_python_deps——被封装在 djevops/remote/actions.py 中，并通过 run_in_django_shell 在 /srv/venv/bin/python 下执行 manage.py，环境变量来自 get_services_users_envs()。资料来源：djevops/remote/actions.py:1-25

失败模式与安全默认

• 缺少依赖声明：init 与 deploy 会同时检查 pyproject.toml 与 requirements.txt；两者都不存在或 django / gunicorn 未声明时，CLI 会直接 CommandError 退出，提示用户提交并推送修改（GIT_HINT）。资料来源：djevops/__main__.py:60-78、djevops/__init__.py:1
• 配置错误：check_django_settings.py 会核对 ALLOWED_HOSTS 中域名/IP 合法性，并强制 DATABASES['default']['NAME'] 与 SQLITE_DB_FILE 环境变量一致。
• 组件一致性：所有远端写入都被 ComponentRegistry 持久化；任何中断后下次 deploy 会以 JSON 为准重新收敛。
• 安全默认：每个服务以独立系统用户运行（ServiceUser），环境变量按服务隔离，端口通过 IptablesRules 收敛至仅暴露 80/443，避免 Postfix 误开 25 端口。资料来源：README.md:secure-defaults

See Also

• 项目概览与命令
• 配置文件 deploy/djevops.yml 详解
• Litestream 备份与 PostgreSQL 接入

概述

djevops 是一款面向 Django 开发者的命令行部署工具，用于将 Django Web 应用部署到 Linux VPS（Ubuntu 或 Debian）上。它不依赖 Docker，因此可以在数秒内完成"推送至生产环境"的操作。相比 Ansible，djevops 专注于 Django 场景，用户需要编写的配置代码显著更少。资料来源：README.md:1-15

安装方式为 pip install djevops，随后在 Django 项目的 Git 仓库中执行 djevops init 即可生成初始配置文件。资料来源：README.md:18-22

核心命令

djevops 提供四个子命令，由 __main__.py 统一调度：

init 命令会校验当前目录是否为 Git 仓库、是否存在远程、是否存在 manage.py，并要求声明依赖。资料来源：djevops/__main__.py:50-60。依赖文件支持 pyproject.toml 与 requirements.txt 两种格式（最新版本扩展支持）。资料来源：djevops/__main__.py:80-100

deploy 流程会通过 ComponentRegistry 注册所需组件，仅在组件描述发生变化时执行安装或更新。资料来源：djevops/remote/component_registry.py:6-25

flowchart LR
    A[本地 djevops deploy] --> B[解析 djevops.yml + secrets.py]
    B --> C[SSH 推送 secrets.json]
    C --> D[远端 ComponentRegistry]
    D --> E[安装/更新组件]
    E --> F[git fetch + reset]
    F --> G[migrate + collectstatic]
    G --> H[重启服务]

配置与密钥管理

deploy/djevops.yml 是核心配置文件，包含 server、git、services、db、mail 等顶层键。最简配置示例如下：

server: 1.2.3.4
git:
  repo: githubuser/mydjangoapp
  branch: main
services:
  web:
    type: django
    env:
      clear:
        ALLOWED_HOSTS: your.website.com
      secret:
        - DJANGO_SECRET_KEY
db:
  type: sqlite

密钥通过 deploy/secrets.py 在本地求值，结果以 secrets.json 形式上传到 /root/.djevops/。资料来源：djevops/remote/scaffold.py:5-15、README.md:60-75]()。这种设计让用户可以硬编码密钥（不入库）、读取环境变量或调用密码管理器，每个服务以独立用户运行，避免环境变量泄露。资料来源：README.md:115-125

部署前 check_django_settings.py 会校验 ALLOWED_HOSTS、DATABASES 等设置是否与配置一致。资料来源：djevops/check_django_settings.py:30-50

数据库与备份

djevops 支持 SQLite 与 PostgreSQL 两种数据库。SQLite 场景下，SQLITE_DB_FILE 环境变量必须指向实际的数据库文件路径。资料来源：djevops/check_django_settings.py:60-70

PostgreSQL 由 djevops/remote/postgres.py 负责：自动创建角色与数据库，并可通过 dump 子命令导出。资料来源：djevops/remote/postgres.py:25-50

备份功能通过 db.backup 段启用：

• SQLite：使用 Litestream 持续复制到 S3/Azure 等对象存储。资料来源：README.md:130-150
• PostgreSQL：通过 cron 周期性执行 pg_dump，sync-interval 需同时为合法的秒数与 cron 表达式。资料来源：djevops/__main__.py:130-145

服务端路径常量定义于 djevops/remote/scaffold.py：STATE_DIR='/root/.djevops'、DEPLOY_CONFIG_PATH、SECRETS_PATH、COMPONENTS_PATH 共同构成状态管理基础。资料来源：djevops/remote/scaffold.py:5-10

运维与监控

服务与日志

每个服务以独立 Linux 用户运行，日志写入 /var/log/<service>.log，由 logrotate 轮转压缩。资料来源：README.md:155-160

远程 Shell

djevops shell 通过 SSH 跳板调用 manage.py shell，免去手动进入容器或虚拟环境的步骤。资料来源：djevops/__main__.py:115-120

SSL 与邮件

ALLOWED_HOSTS 中的域名若指向服务器 IP，djevops 会自动签发并续期 Let's Encrypt 证书。资料来源：README.md:90-100 当 mail 段已配置且 DEBUG=False 时，Django 会在出错时通过 ADMINS` 发送邮件。资料来源：README.md:100-110

安全与更新

djevops 默认开启自动 OS 更新（不包含主版本升级），并通过 iptables 规则阻止未预期端口外联（如 Postfix 场景下的 25 端口）。资料来源：README.md:120-130 远程命令执行通过 util.get_apt_install_cmd 封装，仅在包未安装时执行 apt-get install`。资料来源：djevops/util.py:15-25

常见失败模式

See Also

• README.md — 项目概览与功能清单
• djevops/remote/component_registry.py — 组件注册与幂等安装机制
• djevops/check_django_settings.py — 部署前设置校验逻辑

Pitfall Log / 踩坑日志

项目：mherrmann/djevops

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=48582629 | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48582629 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48582629 | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48582629 | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48582629 | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48582629 | release_recency=unknown