Ajenti 面板 Settings 插件实战指南：config.yml 与 smtp.yml 的界面化配置、SSL 证书管理与邮件中继

后端运维【免费下载链接】ajentiAjenti Core and stock plugins项目地址https://gitcode.com/gh_mirrors/aj/ajenti点击查看免费下载本文以 Ajenti 仓库中 Settings 插件文档 为核心骨架系统讲解 Ajenti 面板内建 Settings设置页面的三大页签General / Security / SMTP relay及配套的 2FA 管理功能。文章将结合plugins/settings插件源码与ajenti-core底层配置实现说明每个配置项如何写入/etc/ajenti/config.yml与/etc/ajenti/smtp.yml以及修改后如何让面板生效帮助读者完整掌握通过 Web 界面管理 Ajenti 全局配置、TLS/客户端证书与邮件中继的实战方案。一、插件定位与页面入口Settings 插件位于 plugins/settings插件元数据 plugin.yml 表明其依赖core、filesystem、passwd三个核心插件版本为0.35图标为wrench。它负责把 Ajenti 全局配置暴露为一个可视化的 Web 页面。从 main.py 的侧边栏注册逻辑可以看到该插件将入口挂载在category:general分类下名称Settings图标cog路径/view/settings页面本体由 resources/partial/index.html 定义是一个包含多个页签uib:tabset的单页视图底部浮动的工具栏提供Save保存与Restart panel重启面板两个按钮。前端的保存逻辑在 index.controller.es 中save()会先调用配置对象的save()持久化config.yml若smtp_config已加载还会调用setSmtpConfig()持久化smtp.ymlrestart()则调用core.restart()触发进程重启。文档明确指出修改设置后必须重启面板才能生效。这一点与底层实现吻合——ajenti-core/aj/core.py的run()在启动阶段一次性加载并固化配置对象aj.config.load()/ensure_structure()运行期间不会重新读取配置文件因此重启是配置生效的唯一途径。二、General 页签绑定、语言、主机名与配色General 页签对应config.yml中的全局外观与监听参数。页面表单元素resources/partial/index.html与config.yml字段一一对应界面项写入的 config.yml 键说明Machine name机器名name面板显示的主机名 / 域名Color tag配色color主题强调色可选default、bluegrey、red、deeporange、orange、green、teal、blue、purpleLanguage语言language界面语言默认en切换时会通过locale.setLanguage()立即生效Binding绑定bind块监听模式与地址Binding 部分支持两种模式TCP 模式填写host监听 IP默认0.0.0.0与port监听端口默认8000UNIX 模式填写socketUnix socket 路径。前端的bind.mode通过按钮组在tcp/unix间切换两种模式下的表单字段互斥显示。修改port或host后只有重启面板才会真正改变监听地址这也是为什么页面会把 Restart panel 按钮与保存按钮并排放置。从源码结构可以推断前端availableColors列表index.controller.es与 配置文件文档 中列出的 9 种取值完全一致且config.data.color的变更会被$watch实时同步到identity.color用于刷新侧边栏等界面的强调色。三、Security 页签认证、会话与 TLS 证书Security 页签是 Settings 插件中功能最密集的部分集中管理认证方式、sudo 提权、会话超时与两套 SSL 证书体系。3.1 认证提供者与 sudoAuthentication provider认证提供者对应auth.provider可选os使用操作系统用户或users使用users.yml中的用户列表由 auth_users 插件 维护。前端切换时会触发provider_warning()弹窗提醒务必保证所选提供者下至少存在一个有效用户否则会被锁在面板之外。Sudo对应auth.allow_sudotrue/false允许登录用户在 sudo 组内执行提权操作。Max session time会话超时对应session_max_time单位为秒默认36001 小时达到后自动登出。3.2 Trusted domains 与 Trusted proxies该区块在config.yml中对应trusted_domains与trusted_proxies两个列表Ajenti 2.2.1 引入前端支持增删条目trusted_domains当面板部署在反向代理之后、或以非本机 FQDN 访问时在此列出允许的域名需包含协议与端口形如http://my.domain.com:8000以避免资源加载问题若配置了密码重置功能列表第一项会被用作重置链接的 URL。trusted_proxies当面板位于一个或多个代理之后填写代理 IP用于获取客户端真实 IP。3.3 SSL 服务端证书SSL 相关设置仅在bind.mode tcp时显示包含Enable SSL对应ssl.enable启用 HTTPS 服务配置文件文档 强烈建议设为true。Force SSL对应ssl.force。启用后 Ajenti 会在 80 端口额外启动一个极简监听器把http://hostname的根路径请求以301 Move Permanently重定向到https://hostname:port其实现见 https_redirect.py。SSL certificate file对应ssl.certificate默认全局证书路径如/etc/ajenti/ajenti.pemPEM 文件需同时包含证书与私钥。它既用于 HTTPS 连接当未设置 FQDN 证书时也作为签发客户端证书的 CA 证书。前端帮助文本特别警告在此处使用 Lets Encrypt 证书会破坏客户端证书生成器自签证书没有问题。SSL FQDN certificate file对应ssl.fqdn_certificate存放专用于域名的证书如 Lets Encrypt 证书不确定时可与上方证书保持一致。Generate a self-signed certificate一键生成自签证书。前端 index.controller.es 会先弹窗警告生成新证书将使所有现有客户端认证证书失效确认后调用后端POST /api/settings/generate/server-certificate。后端对应实现位于 views.pyhandle_api_generate_server_certificateviews.py#L72-L106生成 4096 位 RSA 密钥与一张有效期 10 年的自签证书写入/etc/ajenti/ajenti.pem证书与私钥按 PEM 顺序拼接并返回{path: ...}。前端收到后会自动把ssl.enable置为true、ssl.certificate指向新路径并清空旧的客户端证书列表后保存。handle_test_certificateviews.py#L108-L131在保存前对指定证书文件做一次加载校验load_certificateload_privatekey失败则抛出EndpointError前端据此显示 SSL Error 提示并中止保存。也就是说填写非法证书路径时保存会被后端拦截。3.4 客户端证书认证双向 TLSssl.client_auth子块提供基于证书的客户端认证enable开启客户端证书认证force若为true仅允许使用客户端证书登录为false时仍允许密码登录certificates已注册证书列表每条记录包含digest证书摘要、name证书主体、serial序列号、user绑定的登录用户名由 Settings 页面自动填充。页面提供New certificate对话框可填写登录用户Login as、国家c、州st、组织o、通用名cn点击 Generate 后调用POST /api/settings/generate/client-certificate。后端 views.py#L23-L70 以config.yml中ssl.certificate对应的 PEM 作为 CA签发一张有效期 10 年、SHA-256 签名的客户端证书封装为 PKCS12.p12格式返回 Base64 数据前端将其构造为data:application/x-pkcs12;base64,...下载链接文件名为{user}.p12并把digest/name/serial/user追加进ssl.client_auth.certificates随config.yml一并保存。列表项可一键删除即吊销该客户端证书。该机制的实际配置形态可在仓库示例 ajenti-panel/config.yml 中看到ssl.client_auth下列出已注册证书的digest、name、serial、user四个字段与文档描述完全一致。四、SMTP relay 页签邮件中继与密码重置Smtp relay 页签读写的是独立文件/etc/ajenti/smtp.yml前端在打开页签时调用getSmtpConfig()懒加载该配置。表单包含Email relay启用邮件中继对应config.yml的email.enable开启后才可发送邮件SMTP hostsmtp.server如mail.mydomain.comPortsmtp.port二选一——starttlsTLS587 端口或sslSSL465 端口前端以按钮组呈现SMTP user / SMTP passwordsmtp.user/smtp.password密码输入框带显隐切换Template email reset对应config.yml的email.templates.reset_email即密码重置邮件的 HTML 模板路径。界面还会提示若smtp.yml为空无server当前配置无法实际发送邮件。4.1 smtp.yml 的结构与安全处理/etc/ajenti/smtp.yml的结构由 ajenti-core/aj/config.py 中的SmtpConfig类定义smtp: password: MyVeryStrongStrongPassword port: starttls server: mail.mydomain.com user: mailmydomain.com该类的实现有几个值得注意的安全细节load()在 root 下会把文件权限收紧为0o600config.py#L140-L150并在读入内存后把密码字段置空防止密码泄漏到内存/日志save()收到空密码时自动回填磁盘上已有的真实密码get_smtp_password()避免 Settings 页面保存时意外清空密码config.py#L152-L164。4.2 邮件发送的底层链路邮件中继的实际消费方是 ajenti-core/aj/api/mail.py 中的Mail类目前主要用于密码重置功能。其初始化逻辑会根据smtp.port选择发送通道starttlssmtplib.SMTP(server, 587)starttls(context...)sslsmtplib.SMTP_SSL(server, 465, context...)其他取值发送函数退化为 no-op。send_password_reset()mail.py#L131-L146使用 Jinja2 渲染重置邮件模板默认模板位于 ajenti-core/aj/static/emails/reset_email.html变量包括BASE64_LOGO与RESET_LINK可被email.templates.reset_email覆盖再用 BeautifulSoup 从 HTML 剥离样式生成纯文本版本最后通过选定的 TLS/SSL 通道发出。密码重置的完整流程依赖email.enable与 smtp.yml 凭据同时就绪。五、2FA 页签TOTP 二次验证管理除文档提到的三个页签外Settings 页面还包含2FA页签resources/partial/index.html用于集中管理各用户的 TOTP 二次验证设备。打开页签时调用getTfaConfig()读取/etc/ajenti/tfa.yml列表按用户 认证提供者维度展示User用户名与其认证提供者badge 显示Description设备描述Created创建时间毫秒时间戳经 date 过滤器格式化删除按钮调用config.deleteTfa()移除对应条目。底层配置类为 config.py#L166-L248 中的TFAConfig同样以0o600权限保护文件并在加载时把各条目的secret置空以避免密钥常驻内存TOTP 验证逻辑则由 ajenti-core/aj/security/totp.py 支撑。六、配置文件的完整参考Settings 页面保存的最终落点就是/etc/ajenti下的三个 YAML 文件。以下是仓库 配置文件文档 中整理的完整参数参考可作为手工编辑时的对照依据。6.1 config.yml 关键块auth: allow_sudo: true emails: {} provider: os users_file: /etc/ajenti/users.yml bind: host: 0.0.0.0 mode: tcp port: 8000 ssl: enable: true certificate: /etc/ajenti/mycert.pem fqdn_certificate: /etc/letsencrypt/ajenti.pem force: false client_auth: enable: true force: true certificates: - digest: 15:E8:5E:E5:D2:E8:75:0D:53:FF:22:A8:79:28:E5:BE:33:E0:37:07:FB:31:47:4D:61:69:AB:43:F8:5B:23:78 name: CNA,STNA,Osajenti.mydomain.com,CNrootajenti.mydomain.com serial: 352674123960898230347891590646542168839110009016 user: root email: enable: true templates: reset_email: /etc/ajenti/email/mytemplate_for_reset_password.html color: blue language: en max_sessions: 10 name: ajenti.mydomain.com restricted_user: nobody session_max_time: 1200关键字段速查auth.providerosOS 用户或usersusers.yml 用户auth.allow_sudo控制 sudo 组提权auth.users_file仅在users提供者下生效默认/etc/ajenti/users.yml。注意user_config参数已废弃用户配置现在绑定到provider避免重复条目。ssl.certificate默认全局证书含证书与私钥兼作客户端证书签发 CAssl.fqdn_certificate域名专用证书ssl.force在 80 端口起监听并把 HTTP 根路径 301 重定向到 HTTPS。email.enable开启密码重置邮件功能但还需 smtp.yml 凭据齐备email.templates.reset_email重置邮件模板路径未设置或文件不存在时回退到内置默认模板见 mail.py 的get_template()。全局参数color9 种取值见上文、language默认en、max_sessions最大并发会话数默认99超限时淘汰最旧的闲置会话、session_max_time会话有效期秒数默认3600、restricted_user受限环境如登录页执行操作所用的系统用户默认nobody是重要的安全参数、name域名、logo自定义 Logo 完整路径、trusted_domains/trusted_proxies需含协议与端口见 3.2 节。上述默认值与 ajenti-core/aj/config.py 中BaseConfig.ensure_structure()config.py#L38-L80的setdefault逻辑完全一致例如max_sessions默认 99、session_max_time默认 3600、language默认en、restricted_user默认nobody启动时还会自动把 2.1.38 之前残留在config.yml的auth.users迁移到独立的users.ymlmigrate_users_to_own_configfile()。仓库示例 ajenti-panel/config.yml 可作为完整可运行配置的参考。6.2 users.yml 与密码哈希使用users认证提供者时用户数据存放在auth.users_file默认/etc/ajenti/users.yml由 auth_users 插件 自动维护users: arnaud: email: arnaudmydomain.com fs_root: /home/arnaud password: 73637279707..... permissions: packages:install: false sidebar:view:/view/cron: false uid: 1002字段说明password为 scrypt 派生密钥的十六进制表示permissions为用户权限列表uid为关联的 OS uid用于决定 worker 以哪个身份运行fs_root为文件管理器根目录email用于密码重置。users.yml由 config.py#L250-L295 的AjentiUsers类读写root 下同样以0o600保护。如需手工生成password字段可参考文档给出的 scrypt 示例import scrypt, os bytes scrypt.encrypt(os.urandom(256), password, maxtime1) hex bytes.hex() print(hex)注意scrypt.encrypt产生的并非传统哈希而是一个派生密钥。七、实战建议改完必重启Settings 页面保存后务必点击 Restart panel 或手动重启 Ajenti 进程否则配置不生效配置仅在启动时加载见 core.py。客户端证书流程先在 Security 页签确认ssl.certificate指向自签证书而非 Lets Encrypt 证书再通过 New certificate 生成.p12客户端证书并下载安装到浏览器若要实现纯证书登录将client_auth.force置为true。邮件功能三步走在 SMTP relay 页签填写server、选择starttls/ssl、填入账号密码并保存确认email.enable为true最后用真实账号触发一次密码重置验证链路可参考 pwreset.py 与 mail.py。保护敏感文件smtp.yml、users.yml、tfa.yml在 root 下运行时会自动收紧为0o600请勿手工放宽权限手工编辑这些文件时也应保持该权限避免凭据泄漏。赞分享后端运维【免费下载链接】ajentiAjenti Core and stock plugins项目地址https://gitcode.com/gh_mirrors/aj/ajenti点击查看免费下载相关推荐Ajenti 配置文件完全指南config.yml / smtp.yml / users.yml 结构与参数详解Ajenti 配置文件完全指南config.yml / smtp.yml / users.yml 结构与参数详解 本篇技术指南基于 Ajenti 官方文档 d后端运维Ajenti 2 服务器管理面板完全指南安装、配置、运行与插件扩展Ajenti 2 服务器管理面板完全指南安装、配置、运行与插件扩展 Ajenti 是一个面向 Linux 与 BSD 的模块化服务器管理面板Ajenti 2后端运维BetterDiscord插件设置界面使用Settings组件构建配置页BetterDiscord插件设置界面使用Settings组件构建配置页 你是否还在为Discord插件配置页开发繁琐而头疼从设计UI元素到状态管理每个环桌面应用UI组件上一篇Upscayl批处理全攻略如何实现AI图像放大自动化工作流下一篇React Worker DOM 使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考