docs: 补充项目文档与安全策略

2026-09-07 09:48:55 +08:00
@@ -0,0 +1,27 @@
+# 版本控制与 IDE
+.git
+.gitignore
+.idea/
+.vscode/
+
+# 敏感配置：严禁打进镜像
+.env
+replacements.txt
+
+# 运行时数据
+logs/
+*.log
+*.png
+
+# 虚拟环境与缓存
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+
+# 文档（镜像运行不需要）
+readme.md
+CONTRIBUTING.md
+SECURITY.md
+CHANGELOG.md
+LICENSE
@@ -0,0 +1,18 @@
+# 更新日志
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式。
+
+## [1.0.0] - 2026-09-07
+
+### Added
+
+- 服务器状态监控：定时（60 秒）通过 SSH 采集 `top` 指标（CPU / 内存 / 负载 / 任务状态）
+- PC 端与移动端自适应 Web 面板，支持远程关机 / 重启（带二次确认）
+- 服务器列表通过 `SERVERS_JSON` 环境变量注入，附 `.env.example` 配置模板
+- Docker / docker-compose 部署支持
+
+### Security
+
+- 移除早期版本中硬编码的服务器 IP 与密码（历史已用 `git filter-repo` 清洗重写）
+- 关闭默认 Flask debug 模式（`FLASK_DEBUG` 控制，默认关闭）
+- 新增 `.dockerignore`，防止 `.env` 凭据与本地数据进入镜像层
@@ -0,0 +1,25 @@
+# 贡献指南
+
+感谢关注本项目！欢迎通过 Issue 反馈问题、通过 Pull Request 提交改进。
+
+## 提交 Issue
+
+- 反馈 Bug 时请附上：复现步骤、期望行为、实际行为、运行环境（操作系统 / Python 版本 / Docker 版本）
+- **注意脱敏**：不要在 Issue 中粘贴真实的服务器 IP、账号、密码或日志中的敏感信息
+
+## 提交 Pull Request
+
+1. Fork 本仓库并创建功能分支：
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+2. 保持改动聚焦，一个 PR 只解决一类问题
+3. 提交前自查：
+   - 代码无语法错误（`python -m py_compile app.py test.py`）
+   - 不引入任何硬编码的 IP / 账号 / 密码
+   - 涉及配置的改动需同步更新 `.env.example` 与 `readme.md`
+4. 提交信息使用约定式格式，如 `feat: xxx`、`fix: xxx`、`docs: xxx`、`chore: xxx`
+
+## 安全问题
+
+请勿通过公开 Issue 报告安全漏洞，参见 [SECURITY.md](SECURITY.md)。
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangchuanli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,34 @@
+# 安全策略
+
+## 支持的版本
+
+| 版本 | 支持情况 |
+| --- | --- |
+| master 分支最新代码 | ✅ 支持 |
+
+## 报告漏洞
+
+**请勿通过公开 Issue 报告安全漏洞。**
+
+如发现安全漏洞，请通过 GitHub 私有安全公告（Security Advisories → Report a vulnerability）或私下联系维护者报告。我们会在确认后尽快响应并致谢。
+
+报告时请尽量包含：
+
+- 漏洞类型与影响的文件 / 接口
+- 复现步骤或 PoC
+- 影响评估
+
+## 已知的安全边界
+
+本项目定位为**内网轻量运维面板**，设计上未内置以下能力，部署时请自行加固：
+
+- 无登录认证与 RBAC：任何能访问服务端口的人均可远程关机 / 重启受控服务器
+- 无 CSRF 防护
+- SSH 连接使用 `AutoAddPolicy`，不校验主机指纹，存在中间人风险
+
+请务必通过防火墙、VPN 或反向代理（如 Nginx + BasicAuth）限制访问来源，切勿将服务直接暴露到公网。
+
+## 凭据安全
+
+- 所有服务器凭据通过环境变量（`SERVERS_JSON` 等）注入，仓库中不存在任何真实凭据
+- 请确认 `.env` 已被 `.gitignore` 忽略，切勿将真实凭据提交到仓库或 Issue 中
@@ -51,3 +51,29 @@ docker compose up -d --build
 - 代码中 `AutoAddPolicy()` 会自动接受未知主机指纹，存在中间人风险；对安全要求较高的环境请改为 `RejectPolicy` 并预置 known_hosts。
 - 建议 SSH 使用密钥认证代替密码认证。
 - 生产环境保持 `FLASK_DEBUG` 关闭（默认已关闭）。
+
+## 项目结构
+
+```
+linux_controller/
+├── app.py              # 主程序：Web 服务 + 状态采集 + 控制接口
+├── templates/          # 页面模板（index.html PC 端 / m.html 移动端）
+├── test.py             # SSH 连接测试脚本（凭据同样从环境变量读取）
+├── requirements.txt    # Python 依赖
+├── Dockerfile          # 容器构建
+├── docker-compose.yml  # 编排配置
+├── send.sh             # 部署传输脚本
+└── .env.example        # 环境变量配置模板
+```
+
+## 安全漏洞
+
+发现安全漏洞请勿提交公开 Issue，参见 [SECURITY.md](SECURITY.md)。
+
+## 贡献
+
+欢迎提交 Issue 与 Pull Request，贡献流程参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 许可证
+
+本项目基于 [MIT License](LICENSE) 开源。