azukaar/cosmos-server

Cosmos Server 镜像文档

镜像概述与主要用途

Cosmos是一个自托管平台，用于安全运行服务器应用并具备内置隐私功能。它充当应用的安全网关和服务器管理器，旨在解决日益令人担忧的自托管应用和个人服务器易受***的问题。无论您拥有服务器、NAS还是树莓派，运行着Plex、HomeAssistant或博客等应用，Cosmos都是保护这些应用的理想解决方案。只需在服务器上安装Cosmos，通过它连接应用，即可为所有服务提供开箱即用的内置安全性和稳健性。

核心功能与特性

• 易于使用 🚀👍：安装和使用简单，通过直观的Web界面可从任何设备管理应用
• 用户友好 🧑‍🎨：适合新手和资深用户，轻松集成到现有家庭服务器、已安装应用和新应用中
• SmartShield技术 🧠🛡：自动保护应用，无需手动调整（详见下文）
• 安全认证 👦👩：使用同一账户登录所有应用，支持强安全性和多因素认证
• 最新加密方法 🔒🔑：加密数据并保护隐私，安全性为设计核心而非事后添加
• 反向代理 🔄🔗：内置反向代理，通过UI轻松管理应用及其设置
• 自动HTTPS 🔑📜：使用Certbot/Let's Encrypt自动配置和续期HTTPS证书
• 反机器人 🤖❌：防止机器人访问的工具集，如常见机器人检测、IP检测等
• 反DDoS 🔥⛔️：额外保护措施，如可变超时/限流、IP速率限制和地理黑名单
• 完善的用户管理 🪪❎：邀请亲友访问应用，无需尴尬地共享凭据，支持通过电子邮件请求密码重置
• 容器管理 🐋🔧：轻松管理容器及其设置，保持更新并审计安全性，支持docker-compose
• 模块化 🧩📦：轻松添加新功能和集成，仅运行所需功能（如无需Docker、数据库或HTTPS）
• 开源可见 📖📝：完全透明和可信的源代码

SmartShield技术详解

SmartShield是现代API保护包，旨在通过实施高级速率限制和用户限制来保护API，无需手动调整限制和策略即可高效分配和保护资源。

核心功能：

• 动态速率限制 ✨：基于用户行为计算速率限制，灵活维护API健康而不影响用户体验
• 自适应操作 📈：自动限制超出速率限制的用户，防止过度消耗资源而不突然终止请求
• 用户封禁与警告 🚫：自动实施临时或永久封禁并发出警告，防止***或资源密集型用户滥用API
• 全局请求控制 🌐：通过队列监控和限制服务器上的并发请求总数，确保最佳性能和稳定性
• 基于用户的指标 📊：跟踪用户的请求、数据使用和并发连接，实现详细控制
• 特权访问 🔑：为特定用户组分配特权访问，豁免某些限制，确保***期间服务不中断
• 可自定义策略 ⚙️：修改默认策略以适应特定需求，如请求限制、时间预算等

使用场景与适用范围

Cosmos适用于以下场景：

• 拥有服务器、NAS或树莓派并运行自托管应用（如Plex、HomeAssistant、博客）的用户
• 关注自托管数据安全和隐私保护的个人或小型组织
• 希望简化服务器和应用管理的用户，无论技术水平如何
• 自托管应用开发者，需集成安全认证、用户管理等功能而无需从零开发

为什么选择Cosmos

自托管数据（如Plex服务器、个人照片服务器）面临被黑客***或服务器被劫持的风险（即使在本地网络中）。管理服务器、应用和数据非常复杂，且无法独立完成：如何确保存储家庭照片的服务器应用代码安全？多数应用从未经过审计。

即使像Plex这样的主流应用也曾被黑客***，导致用户数据泄露。最近的LastPass泄露事件正是因为员工的Plex服务器未更新至最新版本，缺少重要安全补丁！

现有自托管工具并非专为您的场景设计：企业工具（如Traefik、NGinx）假设后端运行的代码是可信的，但您运行的服务器应用可能并非如此。此外，许多反向代理和安全工具将重要安全功能锁定在昂贵的商业订阅后，不适合自托管用户。

Cosmos专为解决这些问题而设计，提供安全稳健的方式运行自托管应用，确保数据安全且访问无忧。

Let's Encrypt集成

Cosmos Server可使用Let's Encrypt自动生成和续期应用的HTTPS证书，支持使用DNS挑战的通配符证书。配置步骤：

1. 在配置文件（或UI）的HTTPConfig中添加DNSChallengeProvider
2. 通过环境变量添加相应API令牌

支持的DNS提供商及所需环境变量请参考https://go-acme.github.io/lego/dns/#dns-providers%E3%80%82

面向开发者

如果您是自托管应用开发者，将应用与Cosmos集成可轻松获得：

• 安全认证
• 稳健的HTTP层保护
• HTTPS支持
• 用户管理
• 加密
• 日志记录
• 备份等功能

若用户选择不安装Cosmos，您的应用仍可无缝运行。

认证是复杂的（如何验证密码匹配？使用何种加密？如何存储令牌？如何检查用户权限？）。Cosmos Server提供安全的认证系统，任何应用都可轻松集成。

安装与使用方法

Docker快速安装

使用Docker安装简单便捷：

bash
docker run -d --network host --privileged --name cosmos-server -h cosmos-server --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/mnt/host \
  -v /var/lib/cosmos:/config \
  azukaar/cosmos-server:latest

注意：不要使用UNRAID模板、CASAOS或PORTAINER堆栈安装Cosmos，可能无法正常工作。推荐直接使用上述docker run命令！支持Docker Compose，但在Mac或Windows（无host网络）且无域名的情况下，需手动映射端口，可能影响ip:port访问。

Windows和Mac用户注意事项

Windows和Mac不支持Docker的host网络模式，需替换--network host为端口映射：

bash
docker run -d -p 80:80 -p 443:443 -p 4242:4242/udp --privileged --name cosmos-server -h cosmos-server --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/mnt/host \
  -v /var/lib/cosmos:/config \
  azukaar/cosmos-server:latest

参数说明：

• --network host：使用主机网络（推荐Linux），确保Cosmos能访问所有网络接口
• --privileged：可选，若使用AppArmor或SELinux等硬化软件则必需，也用于Constellation功能
• -v /var/run/docker.sock:/var/run/docker.sock：挂载Docker套接字，允许Cosmos管理容器
• -v /:/mnt/host：可选，允许从Cosmos管理主机文件夹，不挂载则需手动创建容器绑定文件夹
• -v /var/lib/cosmos:/config：持久化存储Cosmos配置

安装后访问

安装完成后，通过http://你的服务器IP访问，按照设置向导操作。请始终使用浏览器隐身模式开始安装，避免浏览器缓存问题。

端口说明

• 4242/UDP：用于Constellation ***功能
• 80/443：默认HTTP/HTTPS端口，Cosmos作为反向代理使用

配置调整

可通过修改配置文件或环境变量调整设置，支持的环境变量参考官方文档。

如有安装问题，可加入***社区获取帮助。