本文档说明如何将 Atlas 项目推送到 GitHub 仓库(默认分支 main,当前版本 v1.8.0)。
- 登录 GitHub
- 点击右上角
+→New repository - 输入仓库名(建议:
Atlas) - 不要勾选 "Initialize this repository with a README"(避免创建冲突)
- 点击
Create repository
# 进入项目目录
cd /path/to/Atlas
# 初始化Git仓库
git init
# 添加所有文件到暂存区(确认 .gitignore 已排除 node_modules / .dev.vars / dist)
git add .
# 提交到本地仓库
git commit -m "chore(release): 初始化 Atlas v1.6.0"# 使用HTTPS方式(简单)
git remote add origin https://github.com/你的用户名/Atlas.git
# 或使用SSH方式(推荐,更安全)
git remote add origin git@github.com:你的用户名/Atlas.git
# 验证远程仓库
git remote -v# 首次推送(设置上游分支)
git push -u origin main
# 如果本地默认分支是master,先重命名
git branch -M main
git push -u origin main# 1. 查看当前状态
git status
# 2. 添加修改的文件
git add . # 添加所有修改
git add filename.txt # 添加特定文件
# 3. 提交更改
git commit -m "feat: 添加新功能描述"
# 4. 推送到远程
git push推荐使用 Conventional Commits 规范:
<type>(<scope>): <subject>
<body>
<footer>
类型(type):
feat: 新功能fix: 修复Bugdocs: 文档更新style: 代码格式(不影响功能)refactor: 重构代码perf: 性能优化test: 测试相关chore: 构建/工具相关
示例:
git commit -m "feat(search): 添加搜索建议功能"
git commit -m "fix(auth): 修复登录Token过期问题"
git commit -m "docs: 更新API文档"
git commit -m "refactor(frontend): 重构组件结构"
git commit -m "feat(config): 新增系统配置管理页面"
git commit -m "security: 增强邮箱验证码限流机制"问题: 推送时提示权限错误
解决方案:
# 使用SSH方式需要先配置SSH密钥
# 参考: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
# 或使用HTTPS + Personal Access Token
# GitHub已不再支持密码认证,需要使用Token问题: 本地分支是master,远程是main
解决方案:
# 重命名本地分支
git branch -M main
# 推送到main分支
git push -u origin main问题: 远程仓库初始化了README,导致推送失败
解决方案:
# 拉取远程更改并合并
git pull origin main --allow-unrelated-histories
# 解决冲突后提交
git add .
git commit -m "merge: 合并远程仓库"
# 推送
git push -u origin main问题: 存在未解决的合并冲突
解决方案:
# 查看冲突文件
git status
# 手动解决冲突后
git add <冲突文件>
git commit -m "merge: 解决合并冲突"
# 或中止合并
git merge --abort
# 强制使用远程版本
git fetch --all
git reset --hard origin/main问题: 提交了错误的代码
解决方案:
# 撤销最近一次提交(保留修改)
git reset --soft HEAD~1
# 撤销最近一次提交(丢弃修改)
git reset --hard HEAD~1已推送到远程时,优先用新的修复提交覆盖错误,而不是重写历史。多人协作或 main 受保护时禁止 force push;确需重写时先确认没有其他人基于该提交工作,并让仓库管理员临时解除保护。
确保项目根目录有 .gitignore 文件:
# 依赖目录
node_modules/
# 构建输出
dist/
build/
# 环境变量
.env
.env.local
.env.*.local
# IDE配置
.idea/
.vscode/
*.swp
*.swo
# 系统文件
.DS_Store
Thumbs.db
# 日志文件
*.log
npm-debug.log*
# Wrangler临时文件
.wrangler/
# TypeScript缓存
*.tsbuildinfo仓库默认分支为
main;历史分支v1/v2/v3已删除,请勿再向这些分支推送。
# 创建新功能分支
git checkout -b feature/new-feature
# 切换回主分支
git checkout main
# 合并分支
git merge feature/new-feature
# 删除已合并的分支
git branch -d feature/new-feature# 拉取最新更改
git pull origin main
# 或使用fetch + merge
git fetch origin
git merge origin/main- 创建功能分支进行开发
- 推送分支到GitHub
- 在GitHub上创建Pull Request
- 代码审查后合并
# 创建功能分支
git checkout -b feature/amazing-feature
# 开发完成后推送
git push origin feature/amazing-feature
# 在GitHub上创建PR,合并后删除分支
git checkout main
git pull
git branch -d feature/amazing-feature# 不要提交敏感信息
# 使用环境变量存储密钥
# 在Cloudflare Dashboard中设置secrets
# 如果不小心提交了敏感信息
# 1. 立即在对应平台轮换/吊销密钥(最重要)
# 2. 从当前版本移除:git rm --cached path/to/sensitive-file 并提交
# 3. 历史记录清理需评估影响范围,由仓库管理员执行并通知所有协作者重新克隆本项目敏感配置应放在 backend/.dev.vars(本地)或 Cloudflare Secrets(生产),两者都不进入版本库。
- 确认
git status、当前分支与远端(git status -sb、git remote -v、git log -1 --oneline) - 同步版本号:根
package.json、backend/package.json、frontend/package.json、packages/shared/package.json、backend/wrangler.toml的APP_VERSION、前后端版本常量、README 徽章与docs/CHANGELOG.md;客户端额外同步desktop/package.json(Android 自动取根版本,见 app-packaging.md) - 在
docs/CHANGELOG.md按「新增 / 修改 / 修复 / 优化」补版本章节 - 按功能分组提交(例如
feat(help): ...、fix(community): ...、docs: ...、chore(release): ...) - 普通推送:
git push origin main。不要 force push,不要跳过 hook - 推送后确认 Cloudflare → Workers & Pages →
atlas→ Deployments 里出现本次提交触发的构建且状态为成功
项目采用 Workers Builds 直连 GitHub 部署:推送到 main 即自动构建(前端产物 + Worker)并部署到 Worker atlas。配置见 deploy.md 第三节第 7 步。
配置文件位置:.github/workflows/backend-deploy.yml
- 仅在 Actions 页面手动触发(
workflow_dispatch);push 不会触发,避免与 Workers Builds 双写互相覆盖 - 流程与 Workers Builds 等价(typecheck → lint → 构建前端 →
wrangler deploy)
在GitHub仓库设置中添加以下Secrets:
| Secret名称 | 说明 |
|---|---|
CLOUDFLARE_API_TOKEN |
Cloudflare API Token(后端部署) |
CLOUDFLARE_ACCOUNT_ID |
Cloudflare 账户 ID(后端部署) |
ATLAS_RANKING_IMPORT_URL |
榜单导入接口完整地址(${BACKEND_URL}/api/internal/rankings/import) |
RANKINGS_IMPORT_SECRET |
榜单导入共享密钥,与 Worker Secret 保持一致 |
JAVDB_USERNAME |
JavDB 账号用户名(榜单抓取登录用) |
JAVDB_PASSWORD |
JavDB 账号密码(榜单抓取登录用) |
- 登录 Cloudflare Dashboard
- 进入 My Profile > API Tokens
- 创建Token,选择 "Edit Cloudflare Workers" 模板
- 复制Token到GitHub Secrets
推送完成后:
- 访问 GitHub 仓库页面
- 确认所有文件已上传
- 检查 README.md 正确显示
- 验证 GitHub Actions 是否成功运行(如有配置)